<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>A guide to robotpkg</title>
  </head>
  <style type="text/css">

/* --- preamble ------------------------------------------------------------ */

body {
  color:		#444;
  background:		#fff;
  font:			normal normal normal small/1.5em Verdana, sans-serif;
  font-size-adjust:     none;
  font-stretch:         normal;

  text-align:		center;
  min-width:		50em;
}

a:link, a:visited {
  color:		#660403;
  font-weight:		normal;
  text-decoration:	none;
}

a:hover {
  color:		#e90017;
  text-decoration:	underline;
}

div.p {
  margin:		1em 0;
}

table td {
  border-style:		none;
  padding:		0 4ex;
}

table td#hline {
  border-top:		1px solid #ccc;
}

table, table tr {
  border:		1px solid #ccc;
}

#content {
  text-align:		left;
  width:		50em;
  margin-left:		auto;
  margin-right:		auto;
}

#frontmatter, #mainmatter {
  width:		90%;
  text-align:		justify;
}

#preamble h1 {
  font-size:		300%;
  line-height:		120%;
  border-bottom:	1px solid #ccc;
  padding-bottom:	1ex;
}


/* --- front matter -------------------------------------------------------- */

#frontmatter h1 {
  width:		111%;

  font-size:		250%;
  line-height:		150%;

  margin:		5ex 0 1ex 0;
}

#frontmatter a {
  font-size:		125%;
  line-height:		1.5em;
}


/* --- main matter --------------------------------------------------------- */

/* chapters */

#mainmatter h1 {
  width:		111%;
  text-align:		right;

  font-size:		250%;
  line-height:		150%;

  margin:		10ex 0 2ex 0;
  border-bottom:	1px solid #ccc;
}

#mainmatter h1 > a {
  font-size:		150%;
  margin:		0;
  padding-right:	10%
}

#mainmatter h2 {
  font-size:		150%;
  line-height:		150%;

  margin:		4ex 0 1ex 0;
}

  </style>
  <body><div id="content">
    <div id="preamble">






 

<div class="p"><!----></div>

   
<div class="p"><!----></div>

<h1 align="center">A guide to robotpkg </h1>

<h3 align="center">Anthony Mallet - <tt>anthony.mallet@laas.fr</tt> </h3>

<h3 align="center">October  9, 2017</h3>

<div class="p"><!----></div>
   
<div class="p"><!----></div>
</div><div id="frontmatter">


<div class="p"><!----></div>
<div class="small">Copyright &#169; 2006-2011,2013 LAAS/CNRS.<br />
Copyright &#169; 1997-2010 The NetBSD Foundation, Inc.<br />
All rights reserved.<br />

<div class="p"><!----></div>
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

<div class="p"><!----></div>

<ol type="1">
<li> Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
<div class="p"><!----></div>
</li>

<li> Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
<div class="p"><!----></div>
</li>
</ol>

<div class="p"><!----></div>
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
</div>

<div class="p"><!----></div>

<h1>Contents </h1><a href="#tth_chAp1"
>1&nbsp; Introduction</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc1.1"
>1.1&nbsp; What is robotpkg?</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc1.2"
>1.2&nbsp; Why robotpkg?</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc1.3"
>1.3&nbsp; Supported platforms</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc1.4"
>1.4&nbsp; Overview</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc1.5"
>1.5&nbsp; Terminology</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc1.6"
>1.6&nbsp; Roles involved in robotpkg</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc1.7"
>1.7&nbsp; Typography</a><br />
<a href="#tth_chAp2"
>2&nbsp; The robotpkg user's guide</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.1"
>2.1&nbsp; Where to get robotpkg and how to keep it up-to-date</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.1.1"
>2.1.1&nbsp; Getting the binary bootstrap kit</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.1.2"
>2.1.2&nbsp; Getting robotpkg for source compilation</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.1.3"
>2.1.3&nbsp; Keeping robotpkg up-to-date</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.2"
>2.2&nbsp; Bootstrapping robotpkg</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.2.1"
>2.2.1&nbsp; Bootstrapping via the binary kit</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.2.2"
>2.2.2&nbsp; Bootstrapping from source</a><br />


&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.3"
>2.3&nbsp; Using robotpkg</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.3.1"
>2.3.1&nbsp; Building packages from source</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.3.2"
>2.3.2&nbsp; Building packages from a repository checkout</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.3.3"
>2.3.3&nbsp; Installing binary packages</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.3.4"
>2.3.4&nbsp; Removing packages</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.3.5"
>2.3.5&nbsp; Getting information about installed packages</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.3.6"
>2.3.6&nbsp; Other administrative functions</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.3.7"
>2.3.7&nbsp; Available <tt>make</tt> targets</a><br />



&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.4"
>2.4&nbsp; Configuring robotpkg</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.4.1"
>2.4.1&nbsp; Selecting build options</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.4.2"
>2.4.2&nbsp; Selecting build alternatives</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.4.3"
>2.4.3&nbsp; Defining collections of packages</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.4.4"
>2.4.4&nbsp; Package specific configuration variables</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.4.5"
>2.4.5&nbsp; General configuration variables</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.4.6"
>2.4.6&nbsp; Variables affecting the build process</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.4.7"
>2.4.7&nbsp; Additional flags to the compiler</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.5"
>2.5&nbsp; Creating binary packages for everything</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.5.1"
>2.5.1&nbsp; Initial setup</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.5.2"
>2.5.2&nbsp; Running bulk builds</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.5.3"
>2.5.3&nbsp; Generating pretty reports</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc2.5.4"
>2.5.4&nbsp; Automated bulk builds</a><br />
<a href="#tth_chAp3"
>3&nbsp; The robotpkg developer's guide</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc3.1"
>3.1&nbsp; Package files, directories and contents</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc3.1.1"
>3.1.1&nbsp; Makefile</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc3.1.2"
>3.1.2&nbsp; distinfo</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc3.1.3"
>3.1.3&nbsp; PLIST</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc3.1.4"
>3.1.4&nbsp; patches/*</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc3.2"
>3.2&nbsp; General operation</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc3.2.1"
>3.2.1&nbsp; Adding build options to a package</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc3.2.2"
>3.2.2&nbsp; Customizing the PLIST</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc3.2.3"
>3.2.3&nbsp; Customizing the semi-automatic PLIST generation</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc3.2.4"
>3.2.4&nbsp; Incrementing versions when fixing an existing package</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc3.2.5"
>3.2.5&nbsp; Substituting variable text in the package files</a><br />
&nbsp;&nbsp;&nbsp;&nbsp;<a href="#tth_sEc3.3"
>3.3&nbsp; The build phase</a><br />

</div><div id="mainmatter">

<div class="p"><!----></div>
 <a id="tth_chAp1"></a><h1>
 1 <br />Introduction</h1>
<a id="chapter:introduction">
</a>

<div class="p"><!----></div>
 <a id="tth_sEc1.1"></a><h2>
1.1&nbsp;&nbsp;What is robotpkg?</h2> 
<div class="p"><!----></div>
The robotics research  community has always been developing  a lot of software,
in order  to illustrate theoretical concepts and  validate algorithms  on board
real robots.  A great amount of this software was  made freely available to the
community, especially for Unix-based systems,  and is usually available in form
of the source code. Therefore, before such software can be used, it needs to be
configured to  the local system, compiled and  installed.  This is exactly what
The Robotics Packages Collection (robotpkg) does.  robotpkg also has some basic
commands  to handle binary packages,  so that not  every user  has to build the
packages for himself, which is a time-costly, cumbersome and error-prone task.

<div class="p"><!----></div>
The robotpkg project was initiated in the <a href="http://www.laas.fr/">Laboratory
for Analysis and Architecture of  Systems</a> (CNRS/LAAS), France.  The motivation
was, on the one hand,  to ease the software   maintenance tasks for the  robots
that are used there.   On the other  hand, roboticists at CNRS/LAAS have always
fostered  an  open-source  development   model  for   the   software they  were
developing.  In order to  help people  working with the  laboratory to  get the
LAAS software  running outside the laboratory,  a package management system was
necessary.

<div class="p"><!----></div>
Although  robotpkg was an  innovative   project in  the robotics community  (it
started in 2006), a lot of general-purpose software packages management systems
were readily available at this time for  a great variety of Unix-based systems.
The main requirements that we wanted  robotpkg to fullfill  were listed and the
best existing package management system  was chosen as  a starting point.   The
biggest requirement was the  capacity of the system to  adapt to the  nature of
the robotic software,  being available mostly in form  of source code  only (no
binary packages),  with unfrequent stable  releases.  robotpkg had thus to deal
mostly with  source code  and automate the  compilation of  the  packages.  The
system chosen  as a starting  point was <a href="http://www.pkgsrc.org">The NetBSD
Packages  Collection</a> (pkgsrc).  robotpkg  can be considered as  a fork of this
project and  it is still very similar  to pkgsrc in  many points, although some
simplifications were made in order to provide  a tool geared toward people that
are not computer scientists but roboticists.

<div class="p"><!----></div>
Due to its  origins, robotpkg provides many packages  developed at LAAS.  It is
however not  limited to such  packages and contains, in  fact, quite some other
software useful to  roboticists.  Of  course, robotpkg  is  not meant to  be  a
general purpose  packaging system   (although  there  would  be   no  technical
restriction to this) and will never  contain widely available packages that can
be found  on  any modern  Unix  distribution. Yet, robotpkg currently  contains
roughly one hundred and fifty packages, including:

<div class="p"><!----></div>

<ul>
<li> architecture/genom - The LAAS Generator of Robotic Components
<div class="p"><!----></div>
</li>

<li> architecture/openrtm - The robotic distributed middleware from AIST, Japan
<div class="p"><!----></div>
</li>

<li> middleware/yarp - The "other", yet famous, robot platform
<div class="p"><!----></div>
</li>

<li> ...just to name a few.
<div class="p"><!----></div>
</li>
</ul>

<div class="p"><!----></div>
 <a id="tth_sEc1.2"></a><h2>
1.2&nbsp;&nbsp;Why robotpkg?</h2> 
<div class="p"><!----></div>
robotpkg provides the following key features:

<div class="p"><!----></div>

<ul>
<li> Easy building of software  from  source as well   as the creation  and
   installation of binary packages. The source and latest patches are retrieved
   from a master download site, checksum verified, then built on your system.
<div class="p"><!----></div>
</li>

<li> All  packages are installed in a  consistent directory tree, including
   binaries, libraries, man pages and other documentation.
<div class="p"><!----></div>
</li>

<li>  Package dependencies, including  when performing package updates, are
   handled automatically.
<div class="p"><!----></div>
</li>

<li> The installation prefix, acceptable  software licenses and  build-time
   options  for a large  number of packages  are all set  in  a simple, central
   configuration file.
<div class="p"><!----></div>
</li>

<li> The  entire framework source  (not including the  package distribution
   files themselves) is freely available under a BSD license, so you may extend
   and adapt robotpkg to your needs, like robotpkg was adapted from pkgsrc.
<div class="p"><!----></div>
</li>
</ul>

<div class="p"><!----></div>
One question often asked by people is "why was robotpkg forked from pkgsrc
instead of integrating the packages into pkgsrc?". This is indeed a very good
question and the following paragraphs try to answer it.

<div class="p"><!----></div>
First,  robotpkg is  not meant  to be  a replacement  for the  system's package
management tool (it does not  superseeds pkgsrc, dpkg, macports etc.). The goal
is to package software that is not widely available on a platform, and which is
mostly  "lab  software" (generally  of  lesser  quality  than widely  available
software).    Those   packages   change   (a   lot)  more   often,   and   more
drastically. Thus, robotpkg is a little bit closer to a "development" tool than
pkgsrc.  Other  "system  packages"  are  correctly handled  by  a  number  of
packaging tools, and there is no need for a new tool.

<div class="p"><!----></div>
Currently, pkgsrc mixes both infrastructure and packages descriptions
themselves. For someone working on e.g. Linux, checking-out
the whole pkgsrc tree would be cumbersome: it would be redundant with the base
Linux package system, plus it would be difficult to isolate the specific
robotic packages from the rest (the rest usually being available in the base
system). robotpkg currently suffers from the same symptom: this may change in
the future if the need for several package repositories becomes blatant.

<div class="p"><!----></div>
robotpkg provides a number of features not available in pkgsrc (and probably
not really useful to pkgsrc either). The most important feature is to be able
to detect "system packages", that are considered as &#235;xternal software not in
robotpkg but usually available on a unix system". pkgsrc has a similar system
but much more limited - to a few base packages only. This is so because pkgsrc
is a full-fledged package system. Thus, it aims at being self contained, while
robotpkg does not.

<div class="p"><!----></div>
Finally, there are a number of additions/changes to the pkgsrc infrastructure
that correspond to legitimate users requests and the specifc workflow in which
robotpkg is used. For instance, robotpkg provides the possibility to generate
an archive of a package from a specific tag in a source repository "on the
fly" or just bypass the archive generation and work directly from the source
repository to install the software. This later workflow is not encouraged, but
it is convenient to quickly test a -current version of some software to see if
it causes any problem. Those features could be ported back to pkgsrc if the
pkgsrc team would find them useful. In the meantime, robotpkg provides a
good testbed for them.

<div class="p"><!----></div>
Still, robotpkg directly uses many of the pkgsrc tools unchanged and the binary
packages are fully compatible.

<div class="p"><!----></div>
 <a id="tth_sEc1.3"></a><h2>
1.3&nbsp;&nbsp;Supported platforms</h2> 
<div class="p"><!----></div>
robotpkg consists of  a   source distribution. After retrieving    the required
source, you can be up and running with robotpkg in just minutes!

<div class="p"><!----></div>
robotpkg  does not have much requirements  by itself and it  can work on a wide
variety of systems  as  long as they   provide a  GNU-make utility, a   working
C-compiler and a small, reasonably standard subset  of Unix commands (like sed,
awk, find,  grep ...).  However, individual packages  might have their specific
requirements.  The   following platforms  have been  reported  to  be supported
reasonably well:

<div class="p"><!----></div>

<div style="text-align:center">
<table border="1" class="tabular">
<tr><td align="center">Platform </td><td align="center">Version
</td></tr><tr><td id="hline" colspan=0></td></tr>

<tr><td align="center">Fedora </td><td align="center">25 or above</td></tr>
<tr><td align="center">Ubuntu </td><td align="center">12.04 or above</td></tr>
<tr><td align="center">Debian </td><td align="center">7 or above</td></tr>
<tr><td align="center">NetBSD </td><td align="center">6 or above</td></tr>
<tr><td align="center">Darwin </td><td align="center">Partial support - infrastructure works, individual packages may not</td></tr></table>
</div>

<div class="p"><!----></div>
Any  other  Unix-like platform  should  usually  work.

<div class="p"><!----></div>
 <a id="tth_sEc1.4"></a><h2>
1.4&nbsp;&nbsp;Overview</h2> 
<div class="p"><!----></div>
This document is divided  into three parts.  <a href="#chapter:user">The first one</a>
describes how  one  can  use  one of   the  packages  in the  Robotics  Package
Collection, either  by installing a precompiled binary  package, or by building
one's own  copy  using  robotpkg.   <a href="#chapter:developer">The  second  part</a>
explains how  to prepare a package so  it can be  easily  built by  other users
without     knowing     about     the     package's    building        details.
<a href="#chapter:internal">The   third part</a> is  intended for  those   who want to
understand how robotpkg is implemented.

<div class="p"><!----></div>
 <a id="tth_sEc1.5"></a><h2>
1.5&nbsp;&nbsp;Terminology</h2> 
<div class="p"><!----></div>
Here is a description of all the terminology used within this document.

<div class="p"><!----></div>

<dl>
 <dt><b>Package</b></dt>
	<dd> A set of files and building instructions that describe what's
   necessary to build a certain piece  of software using robotpkg. Packages are
   traditionally stored under <tt>/opt/robotpkg</tt>.</dd>
 <dt><b>robotpkg</b></dt>
	<dd>  This is  the The Robotics   Package Collection.  It handles
   building (compiling), installing, and removing of packages.</dd>
 <dt><b>Distfile</b></dt>
	<dd> This  term describes the file  or files that are provided by
   the author of the piece of software to distribute  his work. All the changes
   necessary to  build are reflected  in the corresponding package. Usually the
   distfile is in  the form of a  compressed  tar-archive, but other  types are
   possible,     too.    Distfiles   are      usually   stored    below    <tt>
   /opt/robotpkg/distfiles</tt>.</dd>
 <dt><b>Precompiled/binary package</b></dt>
	<dd> A set of binaries built with robotpkg from
   a distfile  and stuffed together in a  single <tt>.tgz</tt> file   so it can be
   installed  on machines of the same  machine architecture without the need to
   recompile. Packages are usually generated in <tt>/opt/robotpkg/packages</tt>.

<div class="p"><!----></div>
   Sometimes, this is  referred to by the  term "package"  too, especially in
   the context of precompiled packages.</dd>
 <dt><b>Program</b></dt>
	<dd>  The  piece  of  software to  be  installed  which  will   be
   constructed from all the files in the distfile by the actions defined in the
   corresponding package.</dd>
</dl>

<div class="p"><!----></div>
 <a id="tth_sEc1.6"></a><h2>
1.6&nbsp;&nbsp;Roles involved in robotpkg</h2> 
<div class="p"><!----></div>

<dl>
 <dt><b>robotpkg users</b></dt>
	<dd> The  robotpkg users  are people  who  use the packages
   provided by robotpkg.  Typically they are student  working  in robotics. The
   usage  of the software  that is <em>inside</em> the  packages is not covered by
   the robotpkg guide.

<div class="p"><!----></div>
   There are two  kinds of robotpkg users:  Some only want to install pre-built
   binary packages.  Others build the robotpkg packages from source, either for
   installing them  directly or for building binary   packages themselves.  For
   robotpkg users, <a href="#chapter:user">Part&nbsp;<a href="#chapter:user">2</a></a>  should provide
   all necessary documentation.</dd>
 <dt><b>package  maintainers</b></dt>
	<dd>   A   package maintainer  creates  packages   as
   described in <a href="#chapter:developer">Part&nbsp;<a href="#chapter:developer">3</a></a>.</dd>
 <dt><b>infrastructure  developers</b></dt>
	<dd>  These people are    involved in all those
   files that live  in the <tt>mk/</tt> directory   and below.  Only  these people
   should             need          to               read               through
   <a href="#chapter:internal">Part&nbsp;</a>, though others might be
   curious, too.</dd>
</dl>

<div class="p"><!----></div>
 <a id="tth_sEc1.7"></a><h2>
1.7&nbsp;&nbsp;Typography</h2> 
<div class="p"><!----></div>
When giving examples for  commands,  shell prompts  are  used  to show if   the
command  should/can be issued  as  root, or if  "normal"  user privileges are
sufficient. We use  a <tt>#</tt>  for  root's shell  prompt, and  a <tt>%</tt>  for
users' shell prompt, assuming they use the C-shell or tcsh.


<div class="p"><!----></div>
 <a id="tth_chAp2"></a><h1>
 2 <br />The robotpkg user's guide</h1>
<a id="chapter:user">
</a>

<div class="p"><!----></div>
Basically, there are two ways of using robotpkg.  The  first is to only install
the  package tools and to  use binary packages that  someone else has prepared.
The second way is  to install the  programs from source. Then  you are  able to
build your own packages,  and you can  still use  binary packages from  someone
else. Sections in this document will detail both approaches where appropriate.

<div class="p"><!----></div>

<div class="p"><!----></div>
 <a id="tth_sEc2.1"></a><h2>
2.1&nbsp;&nbsp;Where to get robotpkg and how to keep it up-to-date</h2> <a id="section:getting">
</a>

<div class="p"><!----></div>
Before you download and extract the files, you need to decide where you want to
extract them and  where you want robotpkg to install  packages.  By defaut, the
<tt>/opt/openrobots</tt> directory is  used. In  the rest  of this  document, the
installation path is called the <em>prefix</em>.

<div class="p"><!----></div>
<tt>robotpkg</tt>  will <em>never</em>  require administration privileges  by itself.
We thus recommend that you do not install or run robotpkg as the root user.  If
something ever goes really  wrong, it might go less wrong if  it is not running
as root. If you want to  install to the default location <tt>/opt/openrobots</tt>,
we recommend that you create this directory owned by a regular user.

<div class="p"><!----></div>
Creating or using <tt>/opt/openrobots</tt> typically requires administration (<em>
a.k.a.</em>  "<tt>root</tt>") privileges.  If  you don't have such privileges (or if
you want  to install to a different  location), you have to  unpack the sources
and  install the  binary packages  in  another prefix.  If you  don't have  any
special administration  rights on the target  machine, a safe bet  is to choose
the <tt>$HOME/openrobots</tt> location, as  the <tt>$HOME</tt>  directory will
always be writable by yourself.

<div class="p"><!----></div>
Any prefix  will work, but please  note that you should  choose an installation
path which is dedicated to robotpkg packages and not shared with other programs
(e.g., we do  not recommend to use  a prefix of <tt>/usr</tt>).   Also, you should
not try to add any of your  own files or directories (such as <tt>src/</tt>) below
the prefix  tree.  This  will prevent possible  conflicts between  programs and
other files  installed by the  package system and  whatever else may  have been
installed there.

<div class="p"><!----></div>
Finally,  the  installation  path   shall  not  contain  white-space  or  other
characters that are interpreted specially by the shell and some other programs:
use only letters, digits, underscores and dashes.

<div class="p"><!----></div>
The rest of this document will  assume that you are using <tt>/opt/openrobots</tt>
as the prefix. You should adapt this path to whatever prefix you choosed.

<div class="p"><!----></div>
     <a id="tth_sEc2.1.1"></a><h3>
2.1.1&nbsp;&nbsp;Getting the binary bootstrap kit</h3>

<div class="p"><!----></div>
At the moment, the  binary bootstrap kit is not  available. Please get the <tt>
robotpkg</tt> sources as described in the next section.

<div class="p"><!----></div>
     <a id="tth_sEc2.1.2"></a><h3>
2.1.2&nbsp;&nbsp;Getting robotpkg for source compilation</h3>

<div class="p"><!----></div>
<tt>robotpkg</tt>    sources   are       distributed     <em>via</em>  the
<a href="http://git-scm.com/"><tt>git</a></tt>  software  content management system.  <tt>
git</tt> will probably be readily available on your system but if you don't have it
installed   or if you    are  unsure  about it,   contact  your  local   system
administrator.

<div class="p"><!----></div>
There are two download methods: the anonymous one and the authenticated
one:

<div class="p"><!----></div>

<ul>
<li>  Anonymous download is the  recommended method if  you  don't intend to
  work on  the   robotpkg infrastructure  itself,  nor commit   any  changes or
  packages  additions  back to  the  robotpkg main repository. Furthermore, the
  possibility to send contributions via patches is still open.

<div class="p"><!----></div>
  As your regular user, simply run in a shell:

<div class="p"><!----></div>

<pre>
%&nbsp;cd&nbsp;/opt/openrobots
%&nbsp;git&nbsp;clone&nbsp;git://git.openrobots.org/robots/robotpkg
%&nbsp;#&nbsp;or
%&nbsp;git&nbsp;clone&nbsp;https://git.openrobots.org/robots/robotpkg.git

</pre>
<div class="p"><!----></div>
</li>

<li> Authenticated   download requires a  valid  login on the  main robotpkg
  repository, and will give you full commit access  to this repository.  Simply
  run the following:

<div class="p"><!----></div>

<pre>
%&nbsp;cd&nbsp;/opt/openrobots
%&nbsp;git&nbsp;clone&nbsp;ssh://git@git.openrobots.org/robots/robotpkg

</pre>
<div class="p"><!----></div>
</li>
</ul>

<div class="p"><!----></div>
     <a id="tth_sEc2.1.3"></a><h3>
2.1.3&nbsp;&nbsp;Keeping robotpkg up-to-date</h3> 
<div class="p"><!----></div>
<tt>robotpkg</tt> is   a   living thing:    updates  to  the packages are     made
perdiodicaly,  problems are fixed,   enhancements  are developed... If   you
downloaded the robotpkg sources via git, you  should keep it up-to-date so that
you get the most  recent packages descriptions. This is done by running <tt>
git pull</tt> in the robotpkg source directory:

<div class="p"><!----></div>

<pre>
%&nbsp;cd&nbsp;/opt/openrobots/robotpkg
%&nbsp;git&nbsp;pull

</pre>

<div class="p"><!----></div>
When you update robotpkg, the git program will only  touch those files that are
registered in the git repository. That means that any packages that you created
on your own will stay unmodified. If you change  files that are managed by git,
later updates will try to merge your changes with those that  have been done by
others. See the <tt>git-pull</tt> manual for details.

<div class="p"><!----></div>
If you want  to be informed  of package additions  and other  updates, a public
mailing    list  is   available    for   your    reading   pleasure.  Go     to
<a href="https://sympa.laas.fr/sympa/info/robotpkg"><tt>https://sympa.laas.fr/sympa/info/robotpkg</tt></a>    for   more  information  and
subscription.


<div class="p"><!----></div>
 <a id="tth_sEc2.2"></a><h2>
2.2&nbsp;&nbsp;Bootstrapping robotpkg</h2> <a id="section:bootstrapping">
</a>

<div class="p"><!----></div>
Once you have  downloaded the robotpkg sources  or the binary bootstrap kit  as
described  in  <a href="#section:getting">Section&nbsp;<a href="#section:getting">2.1</a></a>, a minimal
set  of  the administrative package management  utilities  must be installed on
your system  before you  can  use robotpkg.   This  is  called the  "bootstrap
phase" and  should   be done only   once,  the very  first  time you  download
robotpkg.

<div class="p"><!----></div>
     <a id="tth_sEc2.2.1"></a><h3>
2.2.1&nbsp;&nbsp;Bootstrapping via the binary kit</h3> 
<div class="p"><!----></div>
At the moment, the binary bootstrap kit is not available. Please bootstrap <tt>
robotpkg</tt> as described in the next section.

<div class="p"><!----></div>
     <a id="tth_sEc2.2.2"></a><h3>
2.2.2&nbsp;&nbsp;Bootstrapping from source</h3> 
<div class="p"><!----></div>
You will  need a working C compiler  and the GNU-make   utility version 3.81 or
later.    If you have  extracted  the  robotpkg  archive  into  the standard <tt>
/opt/openrobots/robotpkg</tt> location, installing the   bootstrap kit from  source
should then be as simple as:

<div class="p"><!----></div>

<pre>
%&nbsp;cd&nbsp;/opt/openrobots/robotpkg/bootstrap
%&nbsp;./bootstrap

</pre>

<div class="p"><!----></div>
This will  install various utilities   into <tt>/opt/openrobots/sbin</tt>.

<div class="p"><!----></div>
Should you prefer another installation path, you could use the <tt>--prefix</tt>
option to  change the default  installation prefix.  For  instance, configuring
robotpkg  to  install programs  into  the  openrobots  directory in  your  home
directory can be done like this:

<div class="p"><!----></div>

<pre>
%&nbsp;cd&nbsp;robotpkg/bootstrap
%&nbsp;./bootstrap&nbsp;--prefix=${HOME}/openrobots

</pre>

<div class="p"><!----></div>
<b>After the  bootstrap script  has run,  a message  indicating  the success
should be  displayed.  If  you choosed a  non-standard installation  path, read
this message carefuly</b>, as it contains  instructions that you have to follow in
order  to  setup your  shell  environment  correctly.   These instructions  are
described in the next section.

<div class="p"><!----></div>

<h4>Configuring your environment</h4> 
<div class="p"><!----></div>
If  you configured robotpkg,   during the bootstrap  phase,  to install to some
other location   than <tt>/opt/openrobots</tt>, you  have   to setup manually your
shell environment so that it contains a few  variables holding the installation
path.  Assuming  you invoked bootstrap with <tt>-prefix=/path/to/openrobots</tt>,
you have two options that are compatible with each other:

<div class="p"><!----></div>

<ul>
<li> Add  the directory <tt>/path/to/openrobots/sbin</tt>  to your <tt>PATH</tt>
   variable. robotpkg will    then be able  to find    its administrative tools
   automatically and from that recover other configuration information. This is
   the preferred method.
<div class="p"><!----></div>
</li>

<li> Create the environment variable <tt>ROBOTPKG_BASE</tt> and set its value
   to <tt>/path/to/openrobots</tt>.  robotpkg will  look for this variable  first,
   so it takes precedence over the  first method.  This is  the method you have
   to choose  if  you have  configured  several instances  of robotpkg  in your
   system. This is ony useful in some circumstances and is not normally needed.
<div class="p"><!----></div>
</li>
</ul>

<div class="p"><!----></div>
If  you  don't know  how  to setup   environment variables  permanently in your
system,  please  refer  to  your shell's  manual  or contact  your local system
administrator.

<div class="p"><!----></div>

<h4>The bootstrap script usage</h4> 
<div class="p"><!----></div>
The <tt>bootstrap</tt> script will by default install the package administrative
tools in <tt>/opt/openrobots/sbin</tt>, use <tt>gcc</tt> as the C compiler and <tt>
make</tt> as the GNU-make program. This behaviour can be fine-tuned by using the
following options:

<div class="p"><!----></div>

<dl>
 <dt><b><tt>--prefix &lt;path&#62;</b></dt>
	<dd>   will   select the  prefix  location where
   programs will be installed in.</tt></dd>
 <dt><b><tt>--sysconfdir &lt;path&#62;</b></dt>
	<dd> defaults to <tt>&lt;prefix&#62;/etc</tt>. This is the
   path to the robotpkg configuration file.  Other packages configuration files
   (if any) will also be stored in this directory.</tt></dd>
 <dt><b><tt>--pkgdbdir  &lt;path&#62;</b></dt>
	<dd> defaults to <tt>&lt;prefix&#62;/var/db/pkg</tt>. This
   is the path  to the package database  directory  where robotpkg will  do its
   internal bookkeeping.</tt></dd>
 <dt><b><tt>--compiler &lt;program&#62;</b></dt>
	<dd> defaults to <tt>gcc</tt>.  Use this option if
   you want to use a different C compiler.</tt></dd>
 <dt><b><tt>--make &lt;program&#62;</b></dt>
	<dd> defaults to <tt>make</tt>. Use this option if you
   want to use a different make program. This program should be compatible with
   GNU-make.</tt></dd>
 <dt><b><tt>--help</b></dt>
	<dd>  displays  the <tt>bootstrap</tt> usage.  The comprehensive
   list of recognized options will be displayed.</tt></dd>
</dl>


<div class="p"><!----></div>
 <a id="tth_sEc2.3"></a><h2>
2.3&nbsp;&nbsp;Using robotpkg</h2> 
<div class="p"><!----></div>
After obtaining <tt>robotpkg</tt> , the  <tt>robotpkg</tt> directory now  contains a set of
packages, organized   into  categories.  You can   browse  the online  index of
packages, or run <tt>make index</tt> from the <tt>robotpkg</tt> directory to  build
local <tt>index.html</tt>  files for all  packages, viewable with any web  browser
such as <tt>lynx</tt> or <tt>firefox</tt>.

<div class="p"><!----></div>
<tt>robotpkg</tt> is  essentially based on the  <tt>make(1)</tt> program.  All actions are
triggered by invoking <tt>make</tt> with the proper target. The following sections
document          the           most          useful          ones          and
<a href="#section:using:targets">section&nbsp;<a href="#section:using:targets">2.3.7</a></a> recaps a more
comprehensive list.

<div class="p"><!----></div>
     <a id="tth_sEc2.3.1"></a><h3>
2.3.1&nbsp;&nbsp;Building packages from source</h3> 
<div class="p"><!----></div>
The  first step for  building  a  package  is  downloading the <em>distfiles</em>
(i.e. the unmodified  source). If they have not  yet been downloaded, <tt>robotpkg</tt> 
will  fetch them automatically  and place them  in the <tt>robotpkg/distfiles</tt>
directory.

<div class="p"><!----></div>
Once the software  has  been downloaded,  any  patches will be applied  and the
package will  be compiled for  you.  This may  take some time depending on your
computer, and how many other packages the software depends on and their compile
time.

<div class="p"><!----></div>
For  example,  type the following  commands  at the shell   prompt to build the
robotpkg documentation package:

<div class="p"><!----></div>

<pre>
%&nbsp;cd&nbsp;/opt/openrobots/robotpkg
%&nbsp;cd&nbsp;doc/robotpkg
%&nbsp;make

</pre>

<div class="p"><!----></div>
The next  stage is  to  actually install the newly   compiled package onto your
system. While you   are still in  the directory  for whatever package  you  are
installing, you can do this by entering:

<div class="p"><!----></div>

<pre>
%&nbsp;make&nbsp;install

</pre>

<div class="p"><!----></div>
Installing the package on your system does  not require you  to be root (except
for a few specific  packages). However, if   you bootstraped with a  prefix for
which   you  don't   have  writing   permissions,    <tt>robotpkg</tt> has a     <span class="roman">
just-in-time-sudo</span>  feature,  which allows you to  become  <tt>root</tt>  for the
actual installation step.

<div class="p"><!----></div>
That's it, the software should now be installed   under  the prefix  of the
packages tree - <tt>/opt/openrobots</tt> by default - and setup for use.

<div class="p"><!----></div>
You can now enter:

<div class="p"><!----></div>

<pre>
%&nbsp;make&nbsp;clean

</pre>

<div class="p"><!----></div>
to remove the compiled files in the work  directory, as you shouldn't need them
any more. If  other packages were also  added to your system (dependencies)  to
allow your program to compile, you can also tidy these up with the command:

<div class="p"><!----></div>

<pre>
%&nbsp;make&nbsp;clean-depends

</pre>

<div class="p"><!----></div>
Since  the three tasks of building,  installing and  cleaning correspond to the
typical usage of <tt>robotpkg</tt> , a helper target doing all these tasks exists and is
called <tt>update</tt>. Thus,  to intall a package  with a single command, you can
simply run:

<div class="p"><!----></div>

<pre>
%&nbsp;make&nbsp;update

</pre>

<div class="p"><!----></div>
In addition, <tt>make update</tt> will  also recompile all the installed packages
that were depending on the package that you are updating. This can be quite
time consuming if you are updating a low-level package. Also, note that all
packages that depend on the package you are updating will be deinstalled
first and unavailable in your system until all packages are recompiled and
reinstalled.

<div class="p"><!----></div>

<div class="p"><!----></div>
Occasionally, people want to "look under the covers" to see  what is going on
when a  package  is building  or being  installed.  This may  be for  debugging
purposes, or  out  of simple curiosity. A  number  of utility values have  been
added to help with this.

<div class="p"><!----></div>

<ol type="1">
<li> If you invoke the <tt>make</tt> command with <tt>PKG_DEBUG_LEVEL=1</tt>, then
      a huge amount of information will be displayed. For example,

<div class="p"><!----></div>

<pre>
%&nbsp;make&nbsp;patch&nbsp;PKG_DEBUG_LEVEL=1

</pre>

<div class="p"><!----></div>
      will show all the commands that are invoked, up to and including the
      "patch" stage. Using <tt>PKG_DEBUG_LEVEL=2</tt> will give you even
      more details.
<div class="p"><!----></div>
</li>

<li> If you want to know the value of a certain <tt>make</tt> definition, then
   the <tt>VARNAME</tt> variable   should be used,  in  conjunction with the  <tt>
   show-var</tt> target.  e.g.  to show the  expansion  of the  <tt>make</tt> variable
   <tt>LOCALBASE</tt>:

<div class="p"><!----></div>

<pre>
%&nbsp;make&nbsp;show-var&nbsp;VARNAME=LOCALBASE

</pre>
<div class="p"><!----></div>
</li>
</ol>

<div class="p"><!----></div>

<div class="p"><!----></div>

<div class="p"><!----></div>
     <a id="tth_sEc2.3.2"></a><h3>
2.3.2&nbsp;&nbsp;Building packages from a repository checkout</h3> <a id="section:using:checkout">
</a>

<div class="p"><!----></div>
Before building a  package, <tt>robotpkg</tt> fetches the sources  from the official(s)
download  location(s),  as  instructed  by the  <tt>MASTER_SITES</tt>  variable.
This is the standard and expected behaviour when you work with stable packages.

<div class="p"><!----></div>
Occasionally, though,  it is useful to fetch  a snapshot of the  sources from a
development repository. For instance, one  might want to quickly test a release
candidate of a  package, or fix a simple  bug and create a patch  from the fix.
Whenever a package defines  the <tt>MASTER_REPOSITORY</tt> variable, <tt>robotpkg</tt> is
able to temporarily  work with the repository defined in  this variable. At the
moment, <tt>cvs</tt>, <tt>svn</tt> and <tt>git</tt> repositories are supported.

<div class="p"><!----></div>
To enable this feature for a given package,  you have to first instruct
<tt>robotpkg</tt> to work from a '<tt>checkout</tt>' (instead of the stable releases) by
doing '<tt>make checkout</tt>' in the package directory. For instance:

<div class="p"><!----></div>

<pre>
%&nbsp;cd&nbsp;robotpkg/foo/bar
%&nbsp;make&nbsp;checkout

</pre>

<div class="p"><!----></div>
This sets  a permanent flag in the  <em>working</em> directory of  the package and
the <em>checkout</em>  configuration option will be retained  until the next '<tt>
make clean</tt>'. After a '<tt>make  clean</tt>', the configuration option is set back
to its default and <tt>robotpkg</tt> will  work again with stable releases. This option
is set on a <em>per</em> package  basis only: configuring one package to work with
checkouts does not affect the behaviour of other packages.

<div class="p"><!----></div>
After a '<tt>make checkout</tt>' (and until a '<tt>make clean</tt>'), the package has
a regular  checkout in its <em>working</em> subdirectory.  You  can thus manually
edit, commit, switch branches, etc.  in  the package sources, like in any other
repository, by  first <tt>cd</tt>ing into the  working directory, then  using the
usual repository commands (<tt>cvs</tt>, <tt>svn</tt> or <tt>git</tt>).

<div class="p"><!----></div>
Of  course, the  individual  <tt>robotpkg</tt> targets are  still  available from  the
package  entry in  the robotpkg  hierarchy.  You  can for  instance  <tt>'make
patch'</tt>, <tt>'configure'</tt>, <tt>'build'</tt>, <tt>'install'</tt> or <tt>'update'</tt> as
usual. Note that  <tt>robotpkg</tt> is not exactly stateless, and  this is most visible
when  working with  checkouts:  for  instance, after  a  successful <tt>'make
build'</tt>, you  have to do <tt>'make  rebuild'</tt> to force rebuilding  if you have
modified  the  sources.   The  same  holds  for  <tt>'configure'</tt>  (do  <tt>
'reconfigure'</tt>)  or <tt>'install'</tt> (do  'reinstall', but  since  you cannot
install a package  twice, you normally have to use <tt>'make replace'</tt> in the
particular case of reinstalling a package).

<div class="p"><!----></div>
The  <tt>'clean'</tt>  target  is  special,  in  that  it  removes  the  checkout
configuration  option and  all checkouted  sources, including  locally modified
sources. In order to prevent accidental deletion of precious files, you have to
confirm the cleanign with <tt>'clean confirm'</tt>, as in:

<div class="p"><!----></div>

<pre>
%&nbsp;make&nbsp;clean&nbsp;confirm

</pre>

<div class="p"><!----></div>
A  final  remark:  we <em>STRONGLY  DISCOURAGE</em>  the  use  of robotpkg  as  a
development tool  (i.e. using the <tt>'checkout'</tt> feature on  a <em>regular</em>
basis), for at least two reasons:

<div class="p"><!----></div>

<ul>
<li> <tt>robotpkg</tt> is not designed  for this: it  will not really help  you in
   your  daily   development  work,   compared  to  the   manual  configuration
   installation of the software. It will sometimes create even more trouble, by
   ensuring  that all  the software  depending  on the  checkouted software  is
   up-to-date, which is not necessarily something you want to do every time you
   compile.
<div class="p"><!----></div>
</li>

<li>  A checkout  breaks the  notion  of 'release'  and you  loose all  the
   benefits from working with packages.  In particular, you have no clear state
   of what is installed: you cannot easily reproduce the situation of time T at
   time T+n and don't know precisely  who requires which version of what. It is
   much  more  efficient and  robust  to release  frequently  a  software in  a
   development phase, than using a <em>rolling release</em> approach.
<div class="p"><!----></div>
</li>
</ul>

<div class="p"><!----></div>
In our opinion, the <tt>'checkout'</tt>  target use should be limited to testing a
release candidate or  quickly fix a bug  and create a patch from  the fix, that
you commit upstream and put in the patches/ directory until the next release.

<div class="p"><!----></div>
     <a id="tth_sEc2.3.3"></a><h3>
2.3.3&nbsp;&nbsp;Installing binary packages</h3> 
<div class="p"><!----></div>
At the moment, installing binary packages is not documented.

<div class="p"><!----></div>
     <a id="tth_sEc2.3.4"></a><h3>
2.3.4&nbsp;&nbsp;Removing packages</h3> 
<div class="p"><!----></div>
To deinstall a package, it does not matter whether it was installed from source
code or  from a  binary package.  The  <tt>robotpkg_delete</tt> command  does not
know it  anyway.  To delete a  package, you can just  run <tt>robotpkg_delete
&lt;package-name&#62;</tt>.  The package name can be given with or without version number.
Wildcards can  also be used  to deinstall a  set of packages, for  example <tt>
*genom*</tt> all  packages whose  name contain  the word <tt>genom</tt>.  Be  sure to
include them  in quotes,  so that the  shell does  not expand them  before <tt>
robotpkg_delete</tt> sees them.

<div class="p"><!----></div>
The <tt>-r</tt> option is very powerful: it  removes all the packages that require
the package in question and then removes the package itself. For example:

<div class="p"><!----></div>

<pre>
%&nbsp;robotpkg_delete&nbsp;-r&nbsp;genom

</pre>

<div class="p"><!----></div>
will remove genom and all the packages that used it; this allows
upgrading the <tt>genom</tt> package.

<div class="p"><!----></div>
     <a id="tth_sEc2.3.5"></a><h3>
2.3.5&nbsp;&nbsp;Getting information about installed packages</h3> 
<div class="p"><!----></div>
The <tt>robotpkg_info</tt> shows information about installed  packages or binary
package files.

<div class="p"><!----></div>
     <a id="tth_sEc2.3.6"></a><h3>
2.3.6&nbsp;&nbsp;Other administrative functions</h3> 
<div class="p"><!----></div>
The  <tt>robotpkg_admin</tt>  executes  various administrative  functions on  the
package system.

<div class="p"><!----></div>
     <a id="tth_sEc2.3.7"></a><h3>
2.3.7&nbsp;&nbsp;Available <tt>make</tt> targets</h3> <a id="section:using:targets">
</a>

<div class="p"><!----></div>
The following targets are available in a package directory. They can be invoked
by   running  <tt>make  &lt;target&#62;</tt>   after   <tt>cd</tt>ing   into  some   <tt>
robotpkg/category/package</tt>.

<div class="p"><!----></div>

<h4>Source manipulation</h4>

<dl>
 <dt><b><tt>fetch</tt></b></dt>
	<dd> Download the <tt>${DISTFILES}</tt>.</dd>
 <dt><b><tt>extract</tt></b></dt>
	<dd> Extract the contents of <tt>${DISTFILES}</tt> into the
   work directory <tt>${WRKDIR}</tt>.</dd>
 <dt><b><tt>patch</tt></b></dt>
	<dd> Apply local patches available in <tt>${PATCHDIR}</tt>
   (usually the <tt>patches</tt> directory in the package).</dd>
 <dt><b><tt>checkout</tt></b></dt>
	<dd> Extract the sources in <tt>${WRKDIR}</tt> from
   <tt>${MASTER_REPOSITORY}</tt> instead of <tt>${MASTER_SITES}</tt>. This can
   be used to fetch a not yet released version instead of the latest
   release. This is mutually exclusive with the <tt>fetch</tt> and <tt>extract</tt>
   targets. See
   <a href="#section:using:checkout">section&nbsp;<a href="#section:using:checkout">2.3.2</a></a> for
   details.</dd>
 <dt><b><tt>configure</tt></b></dt>
	<dd> Perform the necessary actions to configure the
   sources. This may for instance involve running <tt>configure</tt> or <tt>
   cmake</tt>. If no configuration is required, this step simply does nothing.</dd>
 <dt><b><tt>build</tt></b></dt>
	<dd> Or  just <tt>make</tt>, the default  target. It compiles the
   package locally in <tt>${WRKDIR}</tt>.</dd>
 <dt><b><tt>install</tt></b></dt>
	<dd> Install the package into <tt>${PREFIX}</tt>. The package
   is then available to the rest of the system. If an older version of the
   package is installed and required by other packages, this target requires
   confirmation. Otherwise, any older version of the package is first
   deinstalled.</dd>
 <dt><b><tt>replace</tt></b></dt>
	<dd> Same as <tt>install</tt>, but does not remove packages
   that depend on the replaced package. This saves some time, since already
   installed package are not touched, but if the replaced package is
   incompatible with the older version, you will run into trouble. Use with
   care and when you know what you are doing.</dd>
 <dt><b><tt>clean</tt></b></dt>
	<dd> Tidy the work directory and removes <tt>${WRKDIR}</tt>. If
   the package was extracted using <tt>checkout</tt>, this target requires
   confirmation as it may delete locally modified files that will be lost.</dd>
 <dt><b><tt>update</tt></b></dt>
	<dd> This is a shortcut target for <tt>fetch</tt>, <tt>
   extract</tt>, <tt>configure</tt>, <tt>build</tt>, <tt>install</tt> and <tt>clean</tt>. If
   the package is already installed and up-to-date, the target asks for
   confirmation.</dd>
</dl>

<div class="p"><!----></div>

<h4>Introspection</h4>

<dl>
 <dt><b><tt>show-options</tt></b></dt>
	<dd> Display the list of available alternatives (see
   <a href="#section:configuring:alternatives">section&nbsp;<a href="#section:configuring:alternatives">2.4.2</a></a>)
   and build options (see
   <a href="#section:configuring:build_options">section&nbsp;<a href="#section:configuring:build_options">2.4.1</a></a>).</dd>
 <dt><b><tt>show-depends</tt></b></dt>
	<dd> Recursively display all the required dependencies
   of a package. The results are splitted between system and <tt>robotpkg</tt> 
dependencies, and missing dependencies are indicated.</dd>
 <dt><b><tt>show-var</tt></b></dt>
	<dd> Display the contents of a variable. This must be
   invoked as <tt>make show-var VARNAME=foo</tt>, where <tt>foo</tt> is the name of
   the variable to be displayed.</dd>
</dl>

<div class="p"><!----></div>

<h4>Package sets</h4>

<div class="p"><!----></div>

<dl>
 <dt><b><tt>fetch-depends</tt>, <tt>replace-depends</tt>, <tt>update-depends</tt>, <tt>
   clean-depends</tt></b></dt>
	<dd>
   This runs the same action as <tt>fetch</tt>, <tt>replace</tt>, <tt>update</tt> or
   <tt>clean</tt> (respectively), but on all dependencies of the package,
   including the package itself. Useful to update a meta-packages, for instance.</dd>
 <dt><b><tt>fetch-&lt;set&#62;</tt>, <tt>replace-&lt;set&#62;</tt>, <tt>update-&lt;set&#62;</tt>, <tt>
   clean-&lt;set&#62;</tt></b></dt>
	<dd>
   This runs the same action as <tt>fetch</tt>, <tt>replace</tt>, <tt>update</tt> or
   <tt>clean</tt> (respectively), but on all members of the package set named <tt>
   &lt;set&#62;</tt>. See
   <a href="#section:configuring:sets">section&nbsp;<a href="#section:configuring:sets">2.4.3</a></a> 
   for an explanation of package sets and how to configure them.</dd>
</dl>


<div class="p"><!----></div>
 <a id="tth_sEc2.4"></a><h2>
2.4&nbsp;&nbsp;Configuring robotpkg</h2> <a id="section:configuring">
</a>

<div class="p"><!----></div>
The whole <tt>robotpkg</tt> system is configured  <em>via</em> a single, centralized file,
called <tt>robotpkg.conf</tt>  and  placed  in  the   <tt>/opt/openrobots/etc</tt>
directory  by default.  This location  might be redefined  during the bootstrap
phase,  see  <a href="#section:bootstrapping">Section&nbsp;<a href="#section:bootstrapping">2.2</a></a>.
During    the  bootstrap, an initial configuration     file is created with the
settings you provided to <tt>bootstrap</tt>.

<div class="p"><!----></div>
The  format of  the configuration file   is that of   the usual GNU style  <tt>
Makefile</tt>s. The whole <tt>robotpkg</tt> configuration  is done by setting variables  in
this  file. Note that  you can  define all  kinds of  variables, and no special
error checking (for example for spelling mistakes)  takes place, so you have to
try it out to see if it works.

<div class="p"><!----></div>
     <a id="tth_sEc2.4.1"></a><h3>
2.4.1&nbsp;&nbsp;Selecting build options</h3> <a id="section:configuring:build_options">
</a>

<div class="p"><!----></div>
Some packages have   build time options, usually   to select between  different
dependencies,  enable  optional   support for    big   dependencies or   enable
experimental features.

<div class="p"><!----></div>
To see   which options, if  any, a   package supports,  and  which  options are
mutually exclusive, run <tt>make show-options</tt>. For example:

<div class="p"><!----></div>

<pre>
Any&nbsp;of&nbsp;the&nbsp;following&nbsp;general&nbsp;options&nbsp;may&nbsp;be&nbsp;selected:
&nbsp;&nbsp;&nbsp;api&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Generate&nbsp;module&nbsp;API&nbsp;only
&nbsp;&nbsp;&nbsp;debug&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Produce&nbsp;debugging&nbsp;information&nbsp;for&nbsp;binary&nbsp;programs
*&nbsp;&nbsp;openprs&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Generate&nbsp;OpenPRS&nbsp;client&nbsp;code
*&nbsp;&nbsp;python&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Enable&nbsp;Python&nbsp;client&nbsp;code
*d&nbsp;tcl&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Generate&nbsp;TCL&nbsp;client&nbsp;code
*&nbsp;&nbsp;tclserv_client&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Generate&nbsp;C&nbsp;tclServ&nbsp;client&nbsp;code
&nbsp;&nbsp;&nbsp;xenomai&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Enable&nbsp;Xenomai&nbsp;support

</pre>

<div class="p"><!----></div>
This indicates  that the package  supports a number of options (<tt>api</tt>, <tt>
debug</tt>, <tt>openprs</tt> ...). The currently enabled options are indicated by a
star (<tt>*</tt>) and the default options are shown by the small letter <tt>d</tt> in
front of each option (here, only the <tt>tcl</tt> is enabled by default).

<div class="p"><!----></div>
The following variables can be defined  in <tt>robotpkg.conf</tt> to select which
options to enable for a package:

<div class="p"><!----></div>

<dl>
 <dt><b><tt>PKG_DEFAULT_OPTIONS</tt></b></dt>
	<dd> can be used to select or  disable
   options  for  all packages  that  support them,</dd>
 <dt><b><tt>PKG_OPTIONS.&lt;pkgbase&#62;</tt></b></dt>
	<dd> can  be   used  to select  or
   disable   options specifically for package <tt>&lt;pkgbase&#62;</tt>. Options listed
   in these variables are selected, options prefixed by <tt>-</tt> are disabled
   (e.g. <tt>-tcl</tt> would disable the <tt>tcl</tt> option).</dd>
</dl>

<div class="p"><!----></div>
A few examples:

<div class="p"><!----></div>

<pre>
PKG_DEFAULT_OPTIONS=&nbsp;&nbsp;&nbsp;&nbsp;debug
PKG_OPTIONS.genom=&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;doc&nbsp;-tcl

</pre>

<div class="p"><!----></div>
It is important to note  that options that were  specifically suggested by  the
package  maintainer must be  explicitely removed if you  do not wish to include
the option.  If you  are unsure you  can view the current  state with <tt>make
show-options</tt>.

<div class="p"><!----></div>
The following settings are  consulted in the order  given, and the last setting
that selects or disables an option is used:

<div class="p"><!----></div>

<ol type="1">
<li> the default options as suggested by the package maintainer,
<div class="p"><!----></div>
</li>

<li> <tt>PKG_DEFAULT_OPTIONS</tt>,
<div class="p"><!----></div>
</li>

<li> <tt>PKG_OPTIONS.&lt;pkgbase&#62;</tt>
<div class="p"><!----></div>
</li>
</ol>

<div class="p"><!----></div>
For groups of mutually exclusive options, the last option selected is used, all
others are automatically  disabled.  If  an option of  the  group is explicitly
disabled, the previously selected option,  if any, is used.   It is an error if
no option from  a  required group  of  options is  selected, and  building  the
package will fail.

<div class="p"><!----></div>
     <a id="tth_sEc2.4.2"></a><h3>
2.4.2&nbsp;&nbsp;Selecting build alternatives</h3> <a id="section:configuring:alternatives">
</a>

<div class="p"><!----></div>
Some  packages  have  alternative   dependencies,  usually  to  select  between
equivalent components or versions of components. This is similar to options but
the  configuration  is  done  globally  for  all packages  that  use  the  same
alternatives (this is to ensure consistency between packages).

<div class="p"><!----></div>
To see   which alternatives, if  any, a   package uses, run <tt>make
show-options</tt>. For example:

<pre>
Available&nbsp;c-compiler&nbsp;alternatives&nbsp;(PREFER_ALTERNATIVE.c-compiler):
*1&nbsp;gcc&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Use&nbsp;the&nbsp;GNU&nbsp;C&nbsp;compiler
&nbsp;2&nbsp;clang&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Use&nbsp;the&nbsp;LLVM&nbsp;C&nbsp;compiler
&nbsp;&nbsp;&nbsp;ccache-gcc&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Use&nbsp;ccache&nbsp;and&nbsp;the&nbsp;GNU&nbsp;C&nbsp;compiler
&nbsp;&nbsp;&nbsp;ccache-clang&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Use&nbsp;ccache&nbsp;and&nbsp;the&nbsp;LLVM&nbsp;C&nbsp;compiler

</pre>
This indicates  that the package  supports a <tt>c-compiler</tt>  alternative, for
which <tt>gcc</tt>, <tt>clang</tt>, <tt>ccache-gcc</tt> and <tt>ccache-clang</tt> can be
used. The  currently selected alternative is  shown by the star  (<tt>*</tt>), and
the  user  preferences  (or the  default  if  the  user  has not  set  explicit
preferences) are indicated by the integer in front of the alternative item
(here <tt>gcc</tt> is the preferred alternative, then <tt>clang</tt> should be used
if <tt>gcc</tt> is not available. <tt>ccache</tt> should not be used).

<div class="p"><!----></div>
The following variables can be defined  in <tt>robotpkg.conf</tt> to select which
alternative to use:

<div class="p"><!----></div>

<dl>
 <dt><b><tt>PREFER_ALTERNATIVE.&lt;alt&#62;</tt></b></dt>
	<dd>
   Alternatives are selected by setting the variable corresponding to the
   alternative (<tt>PREFER_ALTERNATIVE.c-compiler</tt> in the example above) to a
   space separated list, sorted by order of preference, containing one or
   several of the items shown by <tt>make show-options</tt>.</dd>
</dl>

<div class="p"><!----></div>
     <a id="tth_sEc2.4.3"></a><h3>
2.4.3&nbsp;&nbsp;Defining collections of packages</h3> <a id="section:configuring:sets">
</a>

<div class="p"><!----></div>
Instead of installing, removing or updating packages one-by-one, you can define
collections  of  packages  in  your  <tt>robotpkg.conf</tt>.  Once  one  or  more
collections  are defined,  they enable  special targets  that work  on  all the
packages of a collection.

<div class="p"><!----></div>
To define a collection, you have to give it a name and list the set of packages
forming  the  collection   in  the  special  <tt>PKGSET</tt>   variable  in  <tt>
robotpkg.conf</tt>. The syntax is the following:

<div class="p"><!----></div>

<pre>
PKGSET.&lt;name&#62;&nbsp;=&nbsp;&lt;list&#62;
PKGSET_DESCR.&lt;name&#62;&nbsp;=&nbsp;short,&nbsp;optional&nbsp;description&nbsp;of&nbsp;the&nbsp;collection

</pre>

<div class="p"><!----></div>
where <tt>&lt;name&#62;</tt> is the name of the collection (any string is valid) and <tt>
&lt;list&#62;</tt>  is  the  list  of  packages  in  the  collection,  in  the  form  <tt>
&lt;category&#62;/&lt;name&#62;</tt>. For instance,

<div class="p"><!----></div>

<pre>
PKGSET.myset&nbsp;=&nbsp;architecture/genom&nbsp;middleware/pocolibs
PKGSET_DESCR.myset&nbsp;=&nbsp;an&nbsp;awesome&nbsp;duo

</pre>

<div class="p"><!----></div>
defines  a collection named  <tt>myset</tt>  that contains  the two  packages <tt>
genom</tt> and <tt>pocolibs</tt> and describes itself with a rather doubtful sentence.

<div class="p"><!----></div>
For each collection <tt>&lt;name&#62;</tt>  defined in <tt>robotpkg.conf</tt>, the following
targets   are   available:  <tt>clean-&lt;name&#62;</tt>,   <tt>fetch-&lt;name&#62;</tt>,   <tt>
extract-&lt;name&#62;</tt>,    <tt>install-&lt;name&#62;</tt>,    <tt>replace-&lt;name&#62;</tt>,    <tt>
update-&lt;name&#62;</tt>  and <tt>deinstall-&lt;name&#62;</tt>. They  perform the  same  action as
their  respective counterpart without  <tt>-&lt;name&#62;</tt>  suffix, expect  that they
work on  all packages  of the set.   In addition,  for the <tt>replace</tt>, <tt>
update</tt> and  <tt>deinstall</tt> targets,  they sort the  packages in the  order of
their dependencies so that the job is done a sensible order.

<div class="p"><!----></div>
For  the  user convenience,  two  special  targets  are provided.   The
 "<tt>installed</tt>" collection is always defined and represents all currently
installed packages.  Invoking, for  instance, the <tt>update-installed</tt> target
will therefore update all  currently installed packages.  The "<tt>depends</tt>"
collection is  available only  when the current  working directory is  inside a
package. It merely  defines the current package and all  of its dependencies as
the  sole  elements  of  the  collection.  Invoking,  for  instance,  the  <tt>
update-depends</tt>  target will  update all  dependencies  of the  package in  the
current directory.

<div class="p"><!----></div>
Two <tt>robotpkg.conf</tt> variables affect the default behaviour of <tt>
robotpkg</tt> regarding packages sets:

<div class="p"><!----></div>

<dl>
 <dt><b>PKGSET_FAILSAFE</b></dt>
	<dd> When working on a set, and this variable is set to
   yes, robotpkg will continue with further packages instead of stopping on an
   error. If set to 'no', stop on first error. Default: no.</dd>
 <dt><b>PKGSET_STRICT</b></dt>
	<dd> Specify if package sets should be considered as
   'strict' or include dependencies of packages defined in the set. If set to
   'yes', only package strictly defined in sets are considered. If set to 'no',
   dependencies of packages listed in sets are added to their respective
   sets. Default: no.</dd>
</dl>

<div class="p"><!----></div>
Each of these variables can be defined on a per-collection basis, by adding the
.&lt;name&#62; suffix to the variable name, where &lt;name&#62; is the name of the collection
to be configured.

<div class="p"><!----></div>
     <a id="tth_sEc2.4.4"></a><h3>
2.4.4&nbsp;&nbsp;Package specific configuration variables</h3> 
<div class="p"><!----></div>
In this  section, you can  find variables that  apply to one  specific package.
Each  variable is  suffixed by  <tt>.&lt;pkg&#62;</tt>, where  <tt>&lt;pkg&#62;</tt>  is  the actual
package name to which the variable should apply.

<div class="p"><!----></div>

<dl>
 <dt><b>REPOSITORY.&lt;pkg&#62;</b></dt>
	<dd> locally overrides the default <tt>
   MASTER_REPOSITORY</tt> defined for a package. This is useful if you want to
   work with an alternative, perhaps local, repository when doing a <tt>make
   checkout</tt>.</dd>
 <dt><b>CHECKOUT_VCS_OPTS.&lt;pkg&#62;</b></dt>
	<dd> is a list of options used when fetching a
   package via a <tt>make checkout</tt> command. The options are passed to the
   "cvs checkout", "git clone" or "svn checkout" command that extract the
   source archive.</dd>
</dl>

<div class="p"><!----></div>
     <a id="tth_sEc2.4.5"></a><h3>
2.4.5&nbsp;&nbsp;General configuration variables</h3> 
<div class="p"><!----></div>
In  this  section,  you can   find some  variables   that apply  to  all <tt>robotpkg</tt> 
packages.

<div class="p"><!----></div>

<div class="p"><!----></div>

<dl>
 <dt><b>ACCEPTABLE_LICENSES</b></dt>
	<dd> List of acceptable licenses. Whenever you try to
   build a package  whose license is  not in this  list, you will get  an error
   message that includes instructions on how to change this variable.</dd>
 <dt><b>DISTDIR</b></dt>
	<dd> Where to store the downloaded copies of the original source
   distributions used for building <tt>robotpkg</tt> packages. The default is
   <tt>$ROBOTPKG_DIR/distfiles</tt>.</dd>
 <dt><b>PACKAGES</b></dt>
	<dd> The top level directory for the binary packages. The default
   is  <tt>$ROBOTPKG_DIR/packages</tt>.</dd>
 <dt><b>MASTER_SITE_BACKUP</b></dt>
	<dd> List  of backup locations for distribution files
   if not found locally  or  in <tt>$MASTER_SITES</tt>.  The default  is<br />
   <tt>http://softs.laas.fr/openrobots/robotpkg/distfiles/</tt>.</dd>
 <dt><b>PKG_DEBUG_LEVEL</b></dt>
	<dd> The  level of debugging  output  which is displayed
   whilst making and installing the package.  The  default value for this is 0,
   which will not  display the commands as they  are executed (normal, default,
   quiet  operation); the value 1 will  display all shell commands before their
   invocation,  and  the value  2 will  display both the  shell commands before
   their invocation, and their actual execution progress with <tt>set -x</tt>.</dd>
</dl>

<div class="p"><!----></div>
     <a id="tth_sEc2.4.6"></a><h3>
2.4.6&nbsp;&nbsp;Variables affecting the build process</h3> 
<div class="p"><!----></div>

<dl>
 <dt><b>WRKOBJDIR</b></dt>
	<dd> The top level   directory where, if defined,  the  separate
   working directories will get created.  This is useful for building  packages
   on a different filesystem than the <tt>robotpkg</tt> sources.</dd>
 <dt><b>OBJHOSTNAME</b></dt>
	<dd> If set to yes (the default), use hostname-specific
   working directories, e.g. work.cactus, work.localhost. <tt>OBJHOSTNAME</tt>
   takes precedence over <tt>OBJMACHINE</tt> (see below).</dd>
 <dt><b>OBJMACHINE</b></dt>
	<dd> If set to yes (the default) use machine-specific working
   directories, e.g. work.Linux-i386.</dd>
 <dt><b>DEPENDS_TARGET</b></dt>
	<dd> By default,  dependencies are only installed,  and no
   binary package is  created  for them. You  can  set  this variable  to  <tt>
   package</tt>   to   automatically  create    binary  packages   after installing
   dependencies.</dd>
 <dt><b>LOCALBASE</b></dt>
	<dd> Where packages will be installed. The default value is <tt>
   /opt/openrobots</tt>.  Do not  mix     binary  packages with    different values
   of <tt>LOCALBASE</tt>s!</dd>
 <dt><b>MAKE_JOBS</b></dt>
	<dd> When defined, specifies the maximum number of jobs that
   are run in parallel when building packages with the default action. <tt>
   MAKE_JOBS</tt> only affects the "build" target. <tt>MAKE_JOBS</tt> can be set to
   any positive integer; useful values are around the number of processors on
   the machine.

<div class="p"><!----></div>

<div class="p"><!----></div>
</dd>
</dl>     <a id="tth_sEc2.4.7"></a><h3>
2.4.7&nbsp;&nbsp;Additional flags to the compiler</h3> 
<div class="p"><!----></div>
If you wish  to set compiler variables   such as <tt>CFLAGS</tt>,  <tt>CXXFLAGS</tt>,
<tt>FFLAGS</tt> ... please make sure to use  the <tt>+=</tt>  operator instead of the
<tt>=</tt> operator:

<div class="p"><!----></div>

<pre>
CFLAGS+=&nbsp;-your&nbsp;-flags

</pre>

<div class="p"><!----></div>
Using <tt>CFLAGS=</tt> (i.e.  without the "<tt>+</tt>") may  lead to  problems with
packages that need to add their own flags.

<div class="p"><!----></div>
If you want  to pass flags  to the linker, both in  the configure  step and the
build step, you  can do this  in  two ways.   Either set <tt>LDFLAGS</tt> or <tt>
LIBS</tt>.  The difference between  the two is that  <tt>LIBS</tt> will be appended to
the command line, while <tt>LDFLAGS</tt> come earlier. <tt>LDFLAGS</tt> is pre-loaded
with rpath settings   for machines that support  it.  As with <tt>CFLAGS</tt>  you
should use the <tt>+=</tt> operator:

<div class="p"><!----></div>

<pre>
LDFLAGS+=&nbsp;-your&nbsp;-linkerflags

</pre>


<div class="p"><!----></div>
 <a id="tth_sEc2.5"></a><h2>
2.5&nbsp;&nbsp;Creating binary packages for everything</h2> 
<div class="p"><!----></div>
There are  two ways of  getting a  set of binary  packages: manually building
the packages you need, or using <tt>robotpkg</tt> "bulk build" infrastructure.

<div class="p"><!----></div>
Bulk builds can also be used to test that packages compile and install cleanly,
and <tt>robotpkg</tt> provides reporting tools that can summarize the results of a
"bulk build".

<div class="p"><!----></div>
     <a id="tth_sEc2.5.1"></a><h3>
2.5.1&nbsp;&nbsp;Initial setup</h3> <a id="section:bulk:setup">
</a>

<div class="p"><!----></div>
The required setup for running bulk build merely consists in properly setting
up <tt>robotpkg</tt> itself. Details can be found in sections
<a href="#section:bootstrapping"><a href="#section:bootstrapping">2.2</a></a> and
<a href="#section:configuring"><a href="#section:configuring">2.4</a></a>.

<div class="p"><!----></div>
For instance, setup <tt>robotpkg</tt> in the <tt>/local/robotpkg</tt> directory:

<pre>
	%&nbsp;mkdir&nbsp;-p&nbsp;/local/var/lib
	%&nbsp;cd&nbsp;/local/var/lib
	%&nbsp;git&nbsp;clone&nbsp;git://git.openrobots.org/git/robots/robotpkg
	%&nbsp;cd&nbsp;robotpkg/bootstrap
	%&nbsp;./bootstrap&nbsp;--prefix=/local/robotpkg

</pre>

<div class="p"><!----></div>
You should install at least <tt>pkgtools/pkg_install</tt>, <tt>pkgtools/digest</tt>
and <tt>pkgtools/tnftp</tt>. Optionally, you can install <tt>pkgtools/rbulkit</tt>
that can generate pretty HTML reports
(<a href="#section:bulk:report">section&nbsp;<a href="#section:bulk:report">2.5.3</a></a>).

<pre>
	%&nbsp;cd&nbsp;/local/var/lib/robotpkg
	%&nbsp;cd&nbsp;pkgtools/rbulkit
	%&nbsp;make&nbsp;update

</pre>

<div class="p"><!----></div>
You must configure the prefix  directory where binary packages are built.  This
is important: since binary package  are not relocatable, this directory will be
the installation directory of all  generated packages. However, if you use bulk
builds only as a  way to test the build of your  packages, any directory can be
configured. The following variables can be customized in <tt>robotpkg.conf</tt>:

<div class="p"><!----></div>

<dl>
 <dt><b>BULKBASE?=	/opt/openrobots</b></dt>
	<dd>
   The installation prefix of binary packages. This <b>must</b> be different
   from the <tt>${LOCALBASE}</tt> directory where regular robotpkg packages are
   installed. The default is <tt>/opt/openrobots</tt>.

<div class="p"><!----></div>
   </dd>
 <dt><b>BULK_LOGDIR?=	${LOCALBASE}/var/log/bulk</b></dt>
	<dd>
   The directory where log files are kept. The default is to put log files in
   the regular installation prefix of robotpkg (<tt>
   /local/robotpkg/var/log/bulk</tt> in the example setup above).

<div class="p"><!----></div>
   </dd>
 <dt><b>BULK_TAG</b></dt>
	<dd>
   A name (alphanumeric characters) for that bulk session.  The default name is
   based on the machine operating  system and version.  Giving a different name
   can be  used to distinguish between different  runs, but in this  case it is
   probably easier to pass that variable definition on the command line.</dd>
</dl>

<div class="p"><!----></div>
Finally,    you    must   define    at    least    one    package   set    (see
<a href="#section:configuring:sets">section&nbsp;<a href="#section:configuring:sets">2.4.3</a></a>)
containing  the list  of packages  to  build (running  bulk build  on a  single
package is also supported, but has only limited interest). For instance, create
a "<tt>huge</tt>" and a "<tt>tiny</tt>" set by placing the following definitions
in your <tt>robotpkg.conf</tt> file:

<pre>
	PKGSET_DESCR.huge=	Huge&nbsp;bulk&nbsp;set:&nbsp;everything!
	PKGSET.huge=		*/*:*

	PKGSET_DESCR.tiny=	Tiny&nbsp;bulk&nbsp;set:&nbsp;just&nbsp;one&nbsp;package&nbsp;+&nbsp;dependencies
	PKGSET.tiny=		shell/eltclsh
	PKGSET_STRICT.tiny=	no

</pre>

<div class="p"><!----></div>
     <a id="tth_sEc2.5.2"></a><h3>
2.5.2&nbsp;&nbsp;Running bulk builds</h3> <a id="section:bulk:run">
</a>

<div class="p"><!----></div>
The target for running bulk builds is called <tt>bulk</tt>. You can run a bulk
build for one package by just running <tt>make bulk</tt> in the package
directory. Running <tt>make bulk-depends</tt> would run the bulk target on the
package and all of its dependencies. More useful though is to use some
predefined sets of packages as explained in the previous section:

<pre>
	%&nbsp;cd&nbsp;/local/var/lib/robotpkg
	%&nbsp;make&nbsp;bulk-tiny

</pre>
This would run the <tt>bulk</tt> target on each package of the <tt>tiny</tt> set (see
<a href="#section:configuring:sets">section&nbsp;<a href="#section:configuring:sets">2.4.3</a></a>  for an
explanation of the -&lt;set&#62; targets).

<div class="p"><!----></div>
This should run for a while and enventually populate <tt>${BULK_LOGDIR}</tt>
with lots of log files. You can then examine them manually, or generate some
reports with <tt>rbulkit</tt>.

<div class="p"><!----></div>
     <a id="tth_sEc2.5.3"></a><h3>
2.5.3&nbsp;&nbsp;Generating pretty reports</h3> <a id="section:bulk:report">
</a>

<div class="p"><!----></div>
If you installed the <tt>pkgtools/rbulkit</tt> package, you can use the <tt>
rbulk-report</tt> program (installed in <tt>&lt;prefix&#62;/sbin</tt>) to generate:

<ul>
<li> an <tt>sqlite</tt> database containing the bulk results
<div class="p"><!----></div>
</li>

<li> an HTML report
<div class="p"><!----></div>
</li>
</ul>

<div class="p"><!----></div>
With the sample setup used throughout this chapter, the <tt>sqlite</tt> database
can be populated like so:

<pre>
	%&nbsp;rbulk-report&nbsp;log2db&nbsp;/local/robotpkg/var/log/bulk&nbsp;sqlite.db

</pre>
Note that the command will <em>append</em> the results to a pre-existing <tt>
sqlite.db</tt>. Only results using the same <tt>BULK_TAG</tt> will be overwritten.

<div class="p"><!----></div>
The HTML report can then be updated like so:

<pre>
	%&nbsp;rbulk-report&nbsp;db2html&nbsp;sqlite.db&nbsp;/tmp/bulk-report/

</pre>
The report can then be viewed by pointing a web browser to <tt>
/tmp/bulk-report/index.html</tt>.

<div class="p"><!----></div>
To go further, please read the <tt>rbulk-report(1)</tt> manual for available
commands and options.

<div class="p"><!----></div>
     <a id="tth_sEc2.5.4"></a><h3>
2.5.4&nbsp;&nbsp;Automated bulk builds</h3> <a id="section:bulk:auto">
</a>

<div class="p"><!----></div>
The <tt>pkgtools/rbulkit</tt> package contains  sample scripts and  programs that
can be  used to  automate bulk  builds. First, there  is the  <tt>rbulk-build</tt>
script, that does essentially all the steps described in the previous sections.
See <tt>rbulk-build(1)</tt> for more information. It relies on a properly setup
<tt>robotpkg</tt> and <tt>robotpkg.conf</tt>.

<div class="p"><!----></div>
There are also the <tt>rbulk-watchd</tt> and <tt>rbulk-notify</tt> programs, than can
respectively wait for and signal notifications over TCP. This can be used to
trigger a bulk build in a commit hook, for instance. See <tt>rbulk-watchd(1)</tt>
and <tt>rbulk-notify(1)</tt>.

<div class="p"><!----></div>
Finally, <tt>rbulk-dispatch</tt> and <tt>rbulk-dispatchd</tt> are able to parallelize
jobs on a group of machines according to user defined priorities. See
<tt>rbulk-dispatchd(1)</tt>.


<div class="p"><!----></div>
 <a id="tth_chAp3"></a><h1>
 3 <br />The robotpkg developer's guide</h1>
<a id="chapter:developer">
</a>

<div class="p"><!----></div>
This part of the documentation deals with creating and modifying packages.

<div class="p"><!----></div>

 <a id="tth_sEc3.1"></a><h2>
3.1&nbsp;&nbsp;Package files, directories and contents</h2> <a id="section:pkgvars">
</a>

<div class="p"><!----></div>
Whenever you're preparing a package, there are a number of files involved which
are described in the following sections.

<div class="p"><!----></div>
     <a id="tth_sEc3.1.1"></a><h3>
3.1.1&nbsp;&nbsp;Makefile</h3> <a id="subsection:makefile">
</a>

<div class="p"><!----></div>
Building, installation and creation of a package are all controlled by the
package's Makefile. The Makefile describes various things about a package,
for example from where to get it, how to configure, build, and install it.

<div class="p"><!----></div>
A package Makefile contains several sections that describe the package.

<div class="p"><!----></div>
In the first section there are the following variables, which should appear
exactly in the order given here. The order and grouping of the variables is
mostly historical and has no further meaning.

<div class="p"><!----></div>

<dl>
 <dt><b>PKGREVISION</b></dt>
	<dd> Defines the <tt>robotpkg</tt> revision number of the package. This
   <em>should not be set</em> for a new package. See
   <a href="#section:genvars:PKGREVISION">Section&nbsp;<a href="#section:genvars:PKGREVISION">3.2.4</a></a>
   for details.

<div class="p"><!----></div>
   </dd>
 <dt><b>MASTER_SITES</b></dt>
	<dd> In simple cases, <tt>MASTER_SITES</tt>  defines all URLs
   from where the distfile, whose name is derived from the <tt>DISTNAME</tt>
   variable, is fetched.

<div class="p"><!----></div>
   When actually fetching the distfiles, each item from <tt>MASTER_SITES</tt>
   gets the name of each distfile appended to it, without an intermediate
   slash. Therefore, all site values have to end with a slash or other
   separator character. This allows for example to set <tt>MASTER_SITES</tt> to a
   URL of a CGI script that gets the name of the distfile as a parameter. In
   this case, the definition would look like:
   
<blockquote><div>
      <tt>MASTER_SITES=   http://www.example.com/download.cgi?file=</tt>
   </div></blockquote>

<div class="p"><!----></div>
   There are some predefined values for <tt>MASTER_SITES</tt>, which can be used
   in packages. The names of the variables should speak for themselves.
   
<blockquote><div><tt>
      ${MASTER_SITE_SOURCEFORGE}<br />
      ${MASTER_SITE_GNU}<br />
      ${MASTER_SITE_OPENROBOTS}
   </tt></div></blockquote>

<div class="p"><!----></div>
   If you choose one of these predefined sites, you may want to specify a
   subdirectory of that site. Since these macros may expand to more than one
   actual site, <em>you must</em> use the following construct to specify a
   subdirectory:
   
<blockquote><div><tt>
      MASTER_SITES=&nbsp;${MASTER_SITE_SOURCEFORGE:=project_name/}
   </tt></div></blockquote>
   Note the trailing slash after the subdirectory name.

<div class="p"><!----></div>
   </dd>
 <dt><b>FETCH_METHOD</b></dt>
	<dd> This is the method used to download the distfile from
   <tt>MASTER_SITES</tt>. It defaults to '<tt>archive</tt>' which corresponds to the
   normal situation where distfile is an archive available from <tt>
   MASTER_SITES</tt>, so it normally needs not to be set.

<div class="p"><!----></div>
   However, it can happen that a software provider does not provide any archive
   available for download but has only a public repository. In this case, <tt>
   FETCH_METHOD</tt> can be set to <tt>cvs</tt>, <tt>git</tt> or <tt>svn</tt> according to
   the kind of repository available. <tt>MASTER_SITES</tt> is then interpreted as
   a repository of the form <tt>url[@revision[+module]]</tt>, where the bits
   between square brackets are optional and refer to a particular revision and
   module in the repository located at <tt>url</tt>. <tt>url</tt> can take any form
   supported by the underlying fetch tool (<tt>cvs</tt>, <tt>git</tt> or <tt>
   svn</tt>). It is <em>strongly</em> advised to define at least a specific revision
   to be checked out, so that the package can be reproducibly installed in a
   known state.

<div class="p"><!----></div>
   </dd>
 <dt><b>MASTER_REPOSITORY</b></dt>
	<dd> defines a VCS repository from where a "<tt>make
   checkout</tt>" will download the latest revision of a software. <tt>
   MASTER_REPOSITORY</tt> is a list of 2 or 3 elements. The first element is the
   VCS tool to be used: it must be one of <tt>cvs</tt>, <tt>git</tt> or <tt>svn</tt>.
   The second element is the location of the repository. It must be written in
   a syntax understood by the actual VCS tool. The third optional element is a
   list of specific elements to be checked out instead of the default (the
   whole repository).

<div class="p"><!----></div>
   </dd>
 <dt><b>CHECKOUT_VCS_OPTS</b></dt>
	<dd> is a list of options used when fetching a
   package via a <tt>make checkout</tt> command. The options are passed to the
   "cvs checkout", "git clone" or "svn checkout" command that extract the
   source archive.</dd>
</dl>

<div class="p"><!----></div>
The second section contains information about separately downloaded patches, if any.

<div class="p"><!----></div>

<dl>
 <dt><b>PATCHFILES</b></dt>
	<dd> Name(s) of additional files that contain distribution
   patches distributed by the author or other maintainers. There is no
   default. robotpkg will look for them at <tt>PATCH_SITES</tt>. They will
   automatically be uncompressed before patching if    the names end with .gz
   or .Z.

<div class="p"><!----></div>
   </dd>
 <dt><b>PATCH_SITES</b></dt>
	<dd> Primary location(s) for distribution patch files (see
   <tt>PATCHFILES</tt> above) if not found locally.</dd>
</dl>

<div class="p"><!----></div>
The third section contains the following variables.

<div class="p"><!----></div>

<dl>
 <dt><b>MAINTAINER</b></dt>
	<dd> is the email address of the person who feels responsible
   for this package, and who is most likely to look at problems or questions
   regarding this package. Other developers may contact the <tt>MAINTAINER</tt>
   before making changes to the package, but are not required to do so. When
   packaging a new program, set <tt>MAINTAINER</tt> to yourself. If you really
   can't maintain the package for future updates, set it to
   <tt><tt>&lt;</tt>robotpkg@laas.fr<tt>&gt;</tt></tt>.

<div class="p"><!----></div>
   </dd>
 <dt><b>HOMEPAGE</b></dt>
	<dd> is a URL where users can find more information about the
   package.

<div class="p"><!----></div>
   </dd>
 <dt><b>COMMENT</b></dt>
	<dd> is a one-line description of the package (should not include
   the package name).

<div class="p"><!----></div>
   </dd>
 <dt><b>LICENSE</b></dt>
	<dd> Denoting that a package may be installed and used according
   to a particular license is done by placing the license in <tt>
   robotpkg/licenses</tt> and setting the LICENSE variable to a string identifying
   the license file, e.g. in <tt>shell/eltclsh</tt>:
   
<blockquote><div>
      LICENSE=		2-clause-bsd
   </div></blockquote>

<div class="p"><!----></div>
   The license tag mechanism is intended to address copyright-related issues
   surrounding building, installing and using a package, and not to address
   redistribution issues (see RESTRICTED and NO_PUBLIC_SRC, etc.). Packages
   with redistribution restrictions should set these tags.</dd>
</dl>

<div class="p"><!----></div>
Other variables affecting the build process may be gathered in their own
section.

<div class="p"><!----></div>

<dl>
 <dt><b>PKG_SUPPORTED_OPTIONS</b></dt>
	<dd> is the list of build options supported by the
   package. A number of related variables are used in combination with <tt>
   PKG_SUPPORTED_OPTIONS</tt>. See <a href="#section:genvars:PKG_SUPPORTED_OPTIONS">Section&nbsp;<a href="#section:genvars:PKG_SUPPORTED_OPTIONS">3.2.1</a></a> for details.</dd>
</dl>

<div class="p"><!----></div>
     <a id="tth_sEc3.1.2"></a><h3>
3.1.2&nbsp;&nbsp;distinfo</h3> <a id="subsection:distinfo">
</a>

<div class="p"><!----></div>
The distinfo file contains the message digest, or checksum, of each distfile
needed for the package. This ensures that the distfiles retrieved from the
Internet have not been corrupted during transfer or altered by a malign force
to introduce a security hole. Due to recent rumor about weaknesses of digest
algorithms, all distfiles are protected using both SHA1 and RMD160 message
digests, as well as the file size.

<div class="p"><!----></div>
The distinfo file also contains the checksums for all the patches found in the
patches directory (see
<a href="#subsection:patches">Section&nbsp;<a href="#subsection:patches">3.1.4</a></a>).

<div class="p"><!----></div>
To regenerate the distinfo file, use the <tt>make distinfo</tt> or <tt>make mdi</tt>
command.

<div class="p"><!----></div>
     <a id="tth_sEc3.1.3"></a><h3>
3.1.3&nbsp;&nbsp;PLIST</h3>
<a id="subsection:PLIST">
</a>

<div class="p"><!----></div>
This  file  governs the  files  that  are installed  on  your  system: all  the
binaries, manual pages, etc. There are other directives which may be entered in
this  file,  to control  the  creation and  deletion  of  directories, and  the
location of inserted files.

<div class="p"><!----></div>
The  names used  in the  PLIST are  relative to  the installation  prefix (<tt>
${PREFIX}</tt>),  which  means  that  it  cannot  register  files  outside  this
directory  (absolute path names  are not  allowed). As  a general  sanity rule,
robotpkg must  not alter  any files outside  <tt>${PREFIX}</tt> anyway  and, in
particular, not modify automatically existing configuration files. If a package
needs  to install  files  outside <tt>${PREFIX}</tt>,  the best  option is  to
install   them   with   robotpkg   inside  <tt>${PREFIX}</tt>   (e.g.    <tt>
${PREFIX}/etc</tt> or  <tt>${PREFIX}/var</tt>) and  create a <tt>MESSAGE</tt> file
that will instruct the  user to manually link or copy the  files in question to
their final location. See the package <tt>hardware/ieee1394-kmod</tt> for an
example of such package.

<div class="p"><!----></div>
In  order to  create  or  update a  <tt>PLIST</tt>, you  can  use  the <tt>make
print-PLIST</tt> command  to output  a PLIST that  matches any new  installed files
since  the  package   was  extracted.   This  command  will   generate  a  <tt>
PLIST.guess</tt> file which  you must move manually to  <tt>PLIST</tt> after reviewing
the result  of the semi-automatic  generation. In order  to fine tune  the <tt>
PLIST</tt>  or  its semi-automatic  generation,  specific  variables documented  in
<a href="#section:genvars:PLIST">section&nbsp;<a href="#section:genvars:PLIST">3.2.2</a></a> and
<a href="#section:genvars:print-PLIST">section&nbsp;<a href="#section:genvars:print-PLIST">3.2.3</a></a>
may be used.

<div class="p"><!----></div>
     <a id="tth_sEc3.1.4"></a><h3>
3.1.4&nbsp;&nbsp;patches/*</h3> <a id="subsection:patches">
</a>

<div class="p"><!----></div>
Some packages may not work out-of-the box with robotpkg. Therefore, a number of
custom patch  files may be needed to  make the package work.  These patch files
are found in the <tt>patches/</tt> directory. If you want to share patches between
multiple packages  in robotpkg, e.g. because  they use the  same distfiles, set
<tt>PATCHDIR</tt> to the path where the patch files can be found, e.g.:

<blockquote><div>
   PATCHDIR= ../../devel/boost/patches
</div></blockquote>

<div class="p"><!----></div>
The file names of the patch files must be of the form <tt>patch-*</tt>, and they
are usually named <tt>patch-[a-z][a-z]</tt>. In  the <em>patch</em> phase,  these
patches  are automatically applied  to the  files  in <tt>${WRKSRC}</tt>
directory after extracting them, in alphabetic order.

<div class="p"><!----></div>
The <tt>patch-*</tt> files should be in <tt>diff -bu</tt> format, and apply without a
fuzz to avoid problems.  (To force patches to apply with fuzz  you can set <tt>
PATCH_FUZZ_FACTOR=-F2</tt> in a package's <tt>Makefile</tt>).

<div class="p"><!----></div>
Each patch file should be commented so that any developer who knows the code of
the application  can make some use of  the patch. Special care  should be taken
for the upstream developers, since  we generally want that they accept robotpkg
patches, so there is less work in the future. When adding a patch that corrects
a problem in the distfile (rather than e.g. enforcing robotpkg's view of where
man pages should go), send the patch as a bug report to the maintainer. This
benefits non-robotpkg users of the package, and usually makes it possible to
remove the patch in future version.

<div class="p"><!----></div>
When you add or modify existing patch files, remember to generate the checksums
for the patch files by using the <tt>make mdi</tt> command, see
<a href="#subsection:distinfo">Section&nbsp;<a href="#subsection:distinfo">3.1.2</a></a>.


<div class="p"><!----></div>
 <a id="tth_sEc3.2"></a><h2>
3.2&nbsp;&nbsp;General operation</h2> <a id="section:genvars">
</a>

<div class="p"><!----></div>
     <a id="tth_sEc3.2.1"></a><h3>
3.2.1&nbsp;&nbsp;Adding build options to a package</h3> <a id="section:genvars:PKG_SUPPORTED_OPTIONS">
</a>

<div class="p"><!----></div>
Build options (see <a href="#section:configuring:build_options">section&nbsp;<a href="#section:configuring:build_options">2.4.1</a></a> for details) can be defined
in a package by properly configuring the following variables.

<div class="p"><!----></div>

<dl>
 <dt><b>PKG_SUPPORTED_OPTIONS</b></dt>
	<dd>
   This is a list of build options supported by the package. This variable
   should be set in a package Makefile.  E.g.,

<pre>
	PKG_SUPPORTED_OPTIONS=	ipv6&nbsp;ssl

</pre>
   If this variable is not defined, <tt>PKG_OPTIONS</tt> is set to the empty list
   and the package is otherwise treated as not using the options framework.

<div class="p"><!----></div>
   </dd>
 <dt><b>PKG_OPTION_DESCR.&lt;opt&#62;</b></dt>
	<dd>
   This is the textual description of the option &lt;opt&#62; which is displayed by
   the <tt>make show-options</tt> target. E.g.,

<pre>
	PKG_OPTION_DESCR.bar=	Enable&nbsp;the&nbsp;bar&nbsp;option.

</pre>

<div class="p"><!----></div>
   </dd>
 <dt><b>PKG_OPTION_SET.&lt;opt&#62; (resp. PKG_OPTION_UNSET.&lt;opt&#62;)</b></dt>
	<dd>
   This is a makefile fragment that is evaluated when the option &lt;opt&#62; is set
   (resp unset) for the package. E.g.,

<pre>
	PKG_OPTION_SET.bar=	CFLAGS+=-DBAR
	PKG_OPTION_UNSET.bar=	CFLAGS+=-DNO_BAR

</pre>
   Complex (multiline) <tt>_SET</tt> or <tt>_UNSET</tt> actions can be defined with
   the <tt>define</tt> command of GNU-make. It is for instance possible to add
   additional dependencies: see the example below.

<div class="p"><!----></div>
   </dd>
 <dt><b>PKG_OPTIONS_OPTIONAL_GROUPS</b></dt>
	<dd>
   This is a list of names of groups of mutually exclusive options.  The
   options in each group are listed in <tt>PKG_OPTIONS_GROUP.&lt;groupname&#62;</tt>.
   The most specific setting of any option from the group takes precedence over
   all other options in the group.  Options from the groups will be
   automatically added to <tt>PKG_SUPPORTED_OPTIONS</tt>.

<div class="p"><!----></div>
   </dd>
 <dt><b>PKG_OPTIONS_REQUIRED_GROUPS</b></dt>
	<dd>
   Like <tt>PKG_OPTIONS_OPTIONAL_GROUPS</tt>, but building the packages will
   fail if no option from the group is selected.

<div class="p"><!----></div>
   </dd>
 <dt><b>PKG_OPTIONS_NONEMPTY_SETS</b></dt>
	<dd>
   This is a list of names of sets of options.  At least one option from each
   set must be selected. The options in each set are listed in <tt>
   PKG_OPTIONS_SET.&lt;setname&#62;</tt>.  Options from the sets will be automatically
   added to <tt>PKG_SUPPORTED_OPTIONS</tt>.

<div class="p"><!----></div>
   </dd>
 <dt><b>PKG_OPTIONS_SUFFIX</b></dt>
	<dd>
   The suffix in <tt>PKG_OPTIONS.suffix</tt> variable the user can set to enable
   or disable options specifically for this package. Defaults to <tt>
   ${PKGBASE}</tt>.

<div class="p"><!----></div>
   </dd>
 <dt><b>PKG_SUGGESTED_OPTIONS</b></dt>
	<dd>
   This is a list of build options which are enabled by default. This defaults
   to the empty list.</dd>
</dl>

<div class="p"><!----></div>
Here is an example Makefile fragment for a 'wibble' package. This fragment
should be included in the 'wibble' package Makefile.

<div class="p"><!----></div>

<pre>
	PKG_OPTIONS_SUFFIX=		wibble&nbsp;#&nbsp;this&nbsp;is&nbsp;the&nbsp;default
	PKG_SUPPORTED_OPTIONS=		foo&nbsp;bar
	PKG_OPTIONS_OPTIONAL_GROUPS=	robot
	PKG_OPTIONS_GROUP.robot=	lama&nbsp;hrp2
	PKG_SUGGESTED_OPTIONS=		foo

	PKG_OPTION_DESCR.foo=		Enable&nbsp;the&nbsp;foo&nbsp;option.
	PKG_OPTION_DESCR.bar=		Build&nbsp;with&nbsp;the&nbsp;bar&nbsp;package.
	PKG_OPTION_DESCR.lama=		Build&nbsp;for&nbsp;the&nbsp;lama&nbsp;robot.
	PKG_OPTION_DESCR.hrp2=		Build&nbsp;for&nbsp;the&nbsp;hrp2&nbsp;robot.

	define&nbsp;PKG_OPTION_SET.bar
	&nbsp;CFLAGS+=-DNO_BAR
	&nbsp;include&nbsp;../../pkg/bar/depend.mk
	endef
	PKG_OPTION_UNSET.bar=		CFLAGS+=-DNO_BAR

</pre>

<div class="p"><!----></div>
     <a id="tth_sEc3.2.2"></a><h3>
3.2.2&nbsp;&nbsp;Customizing the PLIST</h3> <a id="section:genvars:PLIST">
</a>

<div class="p"><!----></div>
The packing list of a package is usually computed from the <tt>PLIST</tt> file
located in the package directory. The following variables determine how the
final packing list is setup:

<div class="p"><!----></div>

<dl>
 <dt><b>PLIST_SRC</b></dt>
	<dd>
   The source file(s) for the final packing list.  By default, its value
   is constructed from the PLIST.* files within the package directory:

<pre>
&nbsp;&nbsp;&nbsp;&nbsp;PLIST_SRC+=	${PKGDIR}/PLIST.${OS_KERNEL}
&nbsp;&nbsp;&nbsp;&nbsp;PLIST_SRC+=	${PKGDIR}/PLIST.${OPSYS}
&nbsp;&nbsp;&nbsp;&nbsp;PLIST_SRC+=	${PKGDIR}/PLIST.${MACHINE_ARCH}
&nbsp;&nbsp;&nbsp;&nbsp;PLIST_SRC+=	${PKGDIR}/PLIST.${OPSYS}-${MACHINE_ARCH}
&nbsp;&nbsp;&nbsp;&nbsp;PLIST_SRC+=	${PKGDIR}/PLIST

</pre>
   If a Makefile sets <tt>PLIST_SRC</tt>, the defaults are not used.

<div class="p"><!----></div>
   </dd>
 <dt><b>DYNAMIC_PLIST_DIRS</b></dt>
	<dd>
   A list of directories, absolute or relative to the installation
   <tt>${PREFIX}</tt>, whose contents are dynamically added to the final packing
   list. This is useful to handle non-deterministic packing lists, most notably
   those generated by <tt>doxygen</tt>. This should be used with care, since <tt>
   DYNAMIC_PLIST_DIRS</tt> somewhat defeats the purpose of the packing list.

<div class="p"><!----></div>
   </dd>
 <dt><b>PLIST_SUBST</b></dt>
	<dd>
   The <tt>PLIST</tt> file(s) of a  package may also  contain variable references
   (in the  <tt>${VAR}</tt> form)  that are expanded  at intallation  time.  The
   following variables are supported by default:

<pre>
	PKGBASE
	PKGNAME
	PKGVERSION

	OPSYS
	OS_VERSION
	OS_KERNEL
	OS_KERNEL_VERSION

	PKGMANDIR
	PKGINFODIR

	PLIST.&lt;opt&#62;&nbsp;#&nbsp;for&nbsp;all&nbsp;supported&nbsp;options
	PLIST.no&lt;opt&#62;

</pre>
   <tt>PLIST.&lt;opt&#62;</tt> is special: one such variable is defined for each
   supported build option of the package. It can be used to dynamically enable
   an entry of the packing list, depending on the build options configuration.
   A <tt>${PLIST.&lt;opt&#62;}</tt> variable may only be present only at the beginning
   of a line. Technically, <tt>${PLIST.&lt;opt&#62;}</tt> expands to a packing list
   comment <tt>@comment</tt> when the option <tt>&lt;opt&#62;</tt> is not enabled, and to
   the empty string otherwise.

<div class="p"><!----></div>
   <tt>PLIST.no&lt;opt&#62;</tt> is similar to <tt>PLIST.&lt;opt&#62;</tt>, but it enables a <tt>
   PLIST</tt> entry only if the corresponding option is not enabled.

<div class="p"><!----></div>
   Other substitutions may be added by adding definitions to the <tt>
   PLIST_SUBST</tt> variable. For instance, a package may define the <tt>FOO</tt>
   variable substitution like so:

<pre>
	PLIST_SUBST+=&nbsp;FOO=${FOO}

</pre>
   This would instruct the packing list generator to replace all occurences of
   <tt>${FOO}</tt> by the value of the <tt>${FOO}</tt> variable in the Makefile.

<div class="p"><!----></div>
   </dd>
 <dt><b>GENERATE_PLIST</b></dt>
	<dd>
   A sequence of commands, terminating in a semicolon, that outputs contents
   for a PLIST to stdout and is appended to the contents of
   <tt>${PLIST_SRC}</tt>. The default works for almost all packages, and it is
   usually not needed to define a custom command.

<div class="p"><!----></div>
   </dd>
 <dt><b>PLIST_FILTER</b></dt>
	<dd>
   A sequence of commands, each starting with a pipe, that filter out the
   packing list. This is to be used only in rare situations, and a standard
   package should not need to customize this.</dd>
</dl>

<div class="p"><!----></div>
     <a id="tth_sEc3.2.3"></a><h3>
3.2.3&nbsp;&nbsp;Customizing the semi-automatic PLIST generation</h3> <a id="section:genvars:print-PLIST">
</a>

<div class="p"><!----></div>
The semi-automatic  initial PLIST generation  does not handle  package options.
If  the  list  of  installed  files  depends  on  the  package  build  options,
<tt>${PLIST.&lt;opt&#62;}</tt>       variable       references,       detailed       in
<a href="#section:genvars:PLIST">section&nbsp;<a href="#section:genvars:PLIST">3.2.2</a></a>,    must   be
manually added to the result of <tt>make print-PLIST</tt>.

<div class="p"><!----></div>
     <a id="tth_sEc3.2.4"></a><h3>
3.2.4&nbsp;&nbsp;Incrementing versions when fixing an existing package</h3> <a id="section:genvars:PKGREVISION">
</a>

<div class="p"><!----></div>
When making fixes to an existing package it can be useful to change the version
number in <tt>PKGNAME</tt>. To avoid conflicting with future versions by the
original author, a "r1", "r2", ... suffix can be used on package versions by
setting <tt>PKGREVISION=1</tt> (<tt>2</tt>, ...) in the package Makefile. E.g.

<blockquote><div>
   DISTNAME=             foo-17.42<br />
   PKGREVISION=          9
</div></blockquote>
will result in a <tt>PKGNAME</tt> of "foo-17.42r9". The "r" is treated like a "."
by the package tools.

<div class="p"><!----></div>
<tt>PKGREVISION</tt> should be incremented for any non-trivial change in the
resulting binary package. Without a <tt>PKGREVISION</tt> bump, someone with the
previous version installed has no way of knowing that their package is out
of date. Thus, changes without increasing <tt>PKGREVISION</tt> are essentially
labeled "this is so trivial that no reasonable person would want to
upgrade", and this is the rough test for when increasing <tt>PKGREVISION</tt>
is appropriate. Examples of changes that do not merit increasing <tt>
PKGREVISION</tt> are:

<ul>
<li> Changing <tt>HOMEPAGE</tt>, <tt>MAINTAINER</tt> or comments in Makefile.
<div class="p"><!----></div>
</li>

<li> Changing build variables if the resulting binary package is the same.
<div class="p"><!----></div>
</li>

<li> Changing <tt>DESCR</tt>.
<div class="p"><!----></div>
</li>

<li> Adding <tt>PKG_OPTIONS</tt> if the default options don't change.
<div class="p"><!----></div>
</li>
</ul>

<div class="p"><!----></div>
Examples of changes that do merit an increase to <tt>PKGREVISION</tt> include:

<ul>
<li> Security fixes
<div class="p"><!----></div>
</li>

<li> Changes or additions to a patch file
<div class="p"><!----></div>
</li>

<li> Changes to the <tt>PLIST</tt>
<div class="p"><!----></div>
</li>

<li> A dependency is changed or renamed.
<div class="p"><!----></div>
</li>
</ul>

<div class="p"><!----></div>
<tt>PKGREVISION</tt> must also be incremented when dependencies have ABI changes.

<div class="p"><!----></div>
When a new release of the package is released, the <tt>PKGREVISION</tt> must be
removed.

<div class="p"><!----></div>
     <a id="tth_sEc3.2.5"></a><h3>
3.2.5&nbsp;&nbsp;Substituting variable text in the package files</h3> <a id="section:genvars:SUBST">
</a>

<div class="p"><!----></div>
When you want to replace the same text in multiple files or when the
replacement text varies, patches alone cannot help. This is where the SUBST
framework comes in. It provides an easy-to-use interface for replacing text in
files. Example:

<pre>
&nbsp;&nbsp;&nbsp;SUBST_CLASSES+=&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fix-paths
&nbsp;&nbsp;&nbsp;SUBST_STAGE.fix-paths=&nbsp;&nbsp;&nbsp;&nbsp;pre-configure
&nbsp;&nbsp;&nbsp;SUBST_MESSAGE.fix-paths=&nbsp;&nbsp;Fixing&nbsp;absolute&nbsp;paths.
&nbsp;&nbsp;&nbsp;SUBST_FILES.fix-paths=&nbsp;&nbsp;&nbsp;&nbsp;src/*.c
&nbsp;&nbsp;&nbsp;SUBST_SED.fix-paths=&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-e&nbsp;'s,"/usr/local,"${PREFIX},g'

</pre>

<div class="p"><!----></div>
<tt>SUBST_CLASSES</tt>  is a list  of identifiers that  are used to  identify the
different <tt>SUBST</tt> blocks  that are defined.  The <tt>SUBST</tt>  framework is
used by  <tt>robotpkg</tt> , so it  is important to  always use the <tt>+=</tt> operator
with this variable. Otherwise some substitutions may be skipped.

<div class="p"><!----></div>
The remaining  variables of each <tt>SUBST</tt> block are  parameterized with the
identifier from the first line (<tt>fix-paths</tt> in this case).

<div class="p"><!----></div>
<tt>SUBST_STAGE.*</tt>  specifies the  stage at which  the replacement  will take
place. All combinations  of pre-, do- and post- together with  a phase name are
possible, though only few are  actually used. Most commonly used are post-patch
and pre-configure. Of these two, pre-configure should be preferred because then
it is possible  to run <tt>make  patch</tt> and have the state  after applying the
patches but before making any other changes. This is especially useful when you
are debugging  a package  in order  to create new  patches for  it.  Similarly,
post-build  is preferred  over pre-install,  because the  install  phase should
generally be kept as simple as  possible. When you use post-build, you have the
same files  in the working directory that  will be installed later,  so you can
check if the substitution has succeeded.

<div class="p"><!----></div>
<tt>SUBST_MESSAGE.*</tt> is an  optional text  that is  printed just  before the
substitution is  done.

<div class="p"><!----></div>
<tt>SUBST_FILES.*</tt> is the list  of shell globbing patterns that specifies the
files in which the substitution  will take place.  The patterns are interpreted
relatively  to the <tt>WRKSRC</tt>  directory.

<div class="p"><!----></div>
<tt>SUBST_SED.*</tt>  is a  list of  arguments to <tt>sed(1)</tt> that  specify the
actual substitution.  Every sed command should be prefixed with -e, so that all
<tt>SUBST</tt> blocks look uniform.

<div class="p"><!----></div>
There are some more variables, but they are so seldomly used that they are only
documented in the mk/internal/subst.mk file.


<div class="p"><!----></div>
 <a id="tth_sEc3.3"></a><h2>
3.3&nbsp;&nbsp;The build phase</h2> <a id="section:buildvars">
</a>

<div class="p"><!----></div>
For building a package, a rough equivalent of the following code is executed.

<pre>
&nbsp;&nbsp;&nbsp;for&nbsp;d&nbsp;in&nbsp;${BUILD_DIRS};&nbsp;do&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cd&nbsp;${WRKSRC}&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&amp;&nbsp;cd&nbsp;${d}&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&amp;&nbsp;env&nbsp;${MAKE_ENV}&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;${MAKE_PROGRAM}&nbsp;${BUILD_MAKE_FLAGS}&nbsp;\
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-f&nbsp;${MAKE_FILE}&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;${BUILD_TARGET}
&nbsp;&nbsp;&nbsp;done

</pre>

<div class="p"><!----></div>
The following variables affecting the build process of a package may be defined
in a package <tt>Makefile</tt>:

<div class="p"><!----></div>

<dl>
 <dt><b>NO_BUILD</b></dt>
	<dd> (default: unset). If there is no build step at all, set
   <tt>NO_BUILD</tt> to "yes".

<div class="p"><!----></div>
   </dd>
 <dt><b>MAKE_PROGRAM</b></dt>
	<dd> (default: <tt>MAKE</tt>) is the program used to perform
   the actual build in a package.

<div class="p"><!----></div>
   </dd>
 <dt><b>BUILD_DIRS</b></dt>
	<dd> (default: ".") is a list of pathnames relative to <tt>
   WRKSRC</tt>. In each of these directories, <tt>MAKE_PROGRAM</tt> is run with the
   environment <tt>MAKE_ENV</tt> and arguments <tt>BUILD_MAKE_FLAGS</tt>.

<div class="p"><!----></div>
   </dd>
 <dt><b>BUILD_TARGET</b></dt>
	<dd> (default: "all") is the default <tt>make</tt> target for
   building the package.

<div class="p"><!----></div>
   </dd>
 <dt><b>MAKE_JOBS_SAFE</b></dt>
	<dd> Whether the package supports parallel builds. If set
   to yes, at most <tt>MAKE_JOBS</tt> jobs are carried out in parallel. The
   default value is "yes", and packages that don't support it must explicitly
   set it to "no".</dd>
</dl>


<div class="p"><!----></div>

<div class="p"><!----></div>
    </div></div>
  </body>
</html>
